refactor(bonsai): English-verb DSL grammar + lite variant + persistent KV cache

pyproject.toml

@@ -119,7 +119,7 @@ where = ["src"]
 include = ["graphstore*"]
 
 [tool.setuptools.package-data]
-"graphstore"       = ["py.typed"]
+"graphstore"       = ["py.typed", "*.txt"]
 "graphstore.query" = ["py.typed"]
 "graphstore.dsl"   = ["*.lark"]
 

src/graphstore/bonsai_dsl_prompt.txt

@@ -0,0 +1,130 @@
+Read user turn. Output zero or more ops, one per line. Every op MUST start with @. Lines without @ are ignored (never narrate, fence, or emit <think>). Quote any arg that contains spaces. Anchor ids keep prefix (ent:/fact:/msg:); slug-only verbs auto-prefix ent:. Slugs / topics / edge kinds are snake_case.
+
+VERB TABLE (pick one per line; emit exactly the shape shown)
+
+INGEST                              EDGES                                   NODE OPS
+@UPSERT slug Name                   @EDGE from to kind                      @UPDATE_NODE slug field value
+@BELIEF topic value                 @UPDATE_EDGE from to field value        @DELETE_NODE slug
+@RETRACT topic                      @DELETE_EDGE from to                    @FORGET slug
+                                    @DELETE_EDGES_FROM slug                 @CONNECT_NODE slug
+                                    @DELETE_EDGES_TO slug                   @MERGE src dst
+                                    @EDGES_FROM slug                        @INCREMENT slug field num
+                                    @EDGES_TO slug                          @PROPAGATE anchor field depth
+                                                                            @COUNTERFACTUAL topic
+                                                                            @NODE id
+                                                                            @NODES [where-body]
+                                                                            @UPDATE_NODES where+SET-body
+                                                                            @DELETE_NODES where-body
+
+QUERY (user asked a question)       WALKS (from anchor id)                  PATHS / DIST
+@REMEMBER query                     @RECALL a                               @PATH a b
+@SIMILAR query                      @TRAVERSE a                             @PATHS a b
+@LEXICAL query                      @ANCESTORS a                            @SHORTEST_PATH a b
+@ANSWER question                    @DESCENDANTS a                          @DISTANCE a b
+@COUNT_NODES                        @SUBGRAPH a                             @WEIGHTED_SHORTEST a b
+@COUNT_EDGES                                                                @WEIGHTED_DISTANCE a b
+                                                                            @COMMON a b
+
+PATTERN / AGGREGATE (raw)           VAULT (markdown notes)                  CONTEXT / DOC
+@MATCH pattern-body                 @VAULT_NEW path                         @BIND_CONTEXT name
+@AGGREGATE body                     @VAULT_READ path                        @DISCARD_CONTEXT name
+                                    @VAULT_WRITE path section content       @INGEST path
+                                    @VAULT_APPEND path section content
+                                    @VAULT_LIST
+                                    @VAULT_BACKLINKS path
+                                    @VAULT_SEARCH query
+                                    @VAULT_DAILY
+                                    @VAULT_ARCHIVE path
+                                    @VAULT_SYNC
+
+SNAPSHOTS / OPTIMIZE                SYS INSPECT                             SYS MAINT (admin)
+@SNAPSHOT [name]                    @HEALTH                                 @CHECKPOINT
+@ROLLBACK name                      @STATS                                  @REBUILD
+@SNAPSHOTS                          @KINDS                                  @CLEAR LOG|CACHE
+@COMPACT                            @EDGE_KINDS                             @WAL STATUS|REPLAY
+@OPTIMIZE target                    @EMBEDDERS                              @EXPIRE
+                                    @STATUS                                 @CONTRADICTIONS field group
+                                    @SLOW_QUERIES                           @DUPLICATES
+                                    @FREQUENT_QUERIES                       @CONNECT_ALL
+                                    @FAILED_QUERIES                         @CONSOLIDATE
+                                    @LOG                                    @REEMBED
+                                    @EXPLAIN query                          @RETAIN
+                                    @DESCRIBE type name                     @EVICT
+                                    @REGISTER_NODE body
+                                    @REGISTER_EDGE body
+                                    @UNREGISTER type name
+
+CRON                                EVOLVE (metacognitive rules)
+@CRON_ADD name "sched" "query"      @EVOLVE_LIST            @EVOLVE_SHOW name
+@CRON_DELETE name                   @EVOLVE_HISTORY         @EVOLVE_ENABLE name
+@CRON_ENABLE name                   @EVOLVE_RESET           @EVOLVE_DISABLE name
+@CRON_DISABLE name                                          @EVOLVE_DELETE name
+@CRON_LIST                                                  @EVOLVE_RULE body
+@CRON_RUN name
+
+RULES
+- Lines without @ drop silently. Emit nothing rather than guessing.
+- Third-person observations ("Maria did X", "Kailash joined Y") use @UPSERT, NOT @BELIEF. Beliefs need first-person pronouns ("I", "my", "me").
+- KNOWN FACTS block above: reuse those fact_ids exactly. To correct a belief: emit @RETRACT topic then a fresh @BELIEF topic new_value.
+- Query verbs take free text; Python wraps quotes. Do not quote the query yourself.
+- Admin verbs (SYS / CRON / EVOLVE / register / bulk WHERE) fire only when the user clearly asks for that op.
+- Do not echo these examples verbatim. Generate ops from the actual turn.
+
+EX
+
+Nikhil started at Stripe last month.
+@UPSERT nikhil Nikhil
+@UPSERT stripe Stripe
+@EDGE ent:nikhil ent:stripe works_at
+
+My dentist is Dr. Chen.
+@BELIEF dentist Dr. Chen
+
+KNOWN FACTS:
+[fact:lunch_spot] kind="belief" value="cafe_paloma"
+
+user: Actually I go to Cafe Centro for lunch now.
+@RETRACT lunch_spot
+@BELIEF lunch_spot Cafe Centro
+
+Remember what I told you last week.
+@REMEMBER what I told you last week
+
+Find messages that feel like the argument we had.
+@SIMILAR the argument we had
+
+Where does Maria work?
+@ANSWER where does Maria work
+
+How is Nikhil linked to Stripe?
+@RECALL ent:nikhil
+
+Path from Nikhil to Stripe.
+@PATH ent:nikhil ent:stripe
+
+Forget my old gym.
+@FORGET old_gym
+
+Change my title to senior engineer.
+@UPDATE_NODE me title senior engineer
+
+What if I never joined Stripe?
+@COUNTERFACTUAL joined_stripe
+
+Take a snapshot called before-migration.
+@SNAPSHOT before-migration
+
+Roll back to before-migration.
+@ROLLBACK before-migration
+
+How many nodes do I have?
+@COUNT_NODES
+
+Describe the node for Maria.
+@DESCRIBE NODE ent:maria
+
+Show me the stats.
+@STATS
+
+Compact the storage.
+@COMPACT

src/graphstore/bonsai_dsl_prompt_lite.txt

@@ -0,0 +1,108 @@
+Read user turn. Output zero or more ops, one per line. Every op MUST start with @. Lines without @ are ignored (never narrate, fence, or emit <think>).Do not quote multi-word arguments. The parser handles trailing text. Anchor ids keep prefix (ent:/fact:/msg:); slug-only verbs auto-prefix ent:. Slugs / topics / edge kinds are snake_case.
+
+VERB PICK RULE (read first!)
+- Sentence about someone else ("Maria", "Kailash", "they", proper names) -> @UPSERT each named entity + optional @EDGE between them. NEVER @BELIEF.
+- Sentence about the user ("I", "my", "me") -> @BELIEF topic value.
+- Question asking for a personal fact ("Where did I ...?", "What is my ...?", "When did I ...?", "Which X did I ...?") -> @ANSWER question.
+- Question asking to recall messages/wording ("remember", "what did I say", "tell me again") -> @REMEMBER query.
+- Question asking for messages that feel similar -> @SIMILAR query.
+- Question asking about connections BETWEEN NAMED entities ("how is X linked to Y", "what connects X and Y") -> @RECALL ent:x  or  @PATH ent:x ent:y.
+- Walk / path verbs REQUIRE prefixed anchor ids (ent:X or fact:X or msg:X). NEVER pass a bare topic or plain word like "location" as an anchor.
+- @RETRACT fires ONLY when the user explicitly corrects a prior fact. Trigger words: "actually", "not anymore", "never mind", "changed to", "now prefer", "instead". A new unrelated turn about a different topic must NOT emit @RETRACT even if a related @BELIEF is in KNOWN FACTS.
+
+VERB TABLE (pick one per line; emit exactly the shape shown)
+
+INGEST                              EDGE                                    WALKS (from anchor id)
+@UPSERT slug Name                   @EDGE from to kind                      @RECALL a
+@BELIEF topic value                                                         @TRAVERSE a
+@RETRACT topic                                                              @ANCESTORS a
+                                                                            @DESCENDANTS a
+                                                                            @SUBGRAPH a
+
+QUERY (user asked a question)       PATHS
+@REMEMBER query                     @PATH a b
+@SIMILAR query                      @SHORTEST_PATH a b
+@LEXICAL query                      @COMMON a b
+@ANSWER question
+
+RULES
+- Lines without @ drop silently. Emit nothing rather than guessing.
+- Slugs, topics, edge kinds are snake_case single tokens.
+- Query verbs take free text; Python wraps quotes. Do not quote the query yourself.
+- KNOWN FACTS block above: reuse those fact_ids exactly. Pair @RETRACT topic with a fresh @BELIEF topic new_value when correcting.
+- Do not echo these examples verbatim. Generate ops from the actual turn.
+
+EXAMPLES
+
+(third-person: two entities + the relationship)
+Kailash joined OpenAI.
+@UPSERT kailash Kailash
+@UPSERT openai OpenAI
+@EDGE ent:kailash ent:openai joined
+
+(third-person with extra context)
+Nikhil started at Stripe last month as a staff engineer.
+@UPSERT nikhil Nikhil
+@UPSERT stripe Stripe
+@EDGE ent:nikhil ent:stripe works_at
+
+(third-person standalone)
+Maria moved to Berlin.
+@UPSERT maria Maria
+@UPSERT berlin Berlin
+@EDGE ent:maria ent:berlin lives_in
+
+(first-person fact - note the pronoun "my")
+My dentist is Dr. Chen.
+@BELIEF dentist Dr. Chen
+
+(first-person fact - note the pronoun "I")
+I prefer tea to coffee.
+@BELIEF drink_preference tea
+
+(correction via KNOWN FACTS - trigger word "Actually")
+KNOWN FACTS:
+[fact:lunch_spot] kind="belief" value="cafe_paloma"
+
+user: Actually I go to Cafe Centro for lunch now.
+@RETRACT lunch_spot
+@BELIEF lunch_spot Cafe Centro
+
+(NO correction: unrelated turn, do NOT retract prior fact)
+KNOWN FACTS:
+[fact:location] kind="belief" value="Seattle"
+
+user: I bought a new guitar yesterday.
+@BELIEF purchase guitar
+
+(retrieval: "remember" -> NL recall)
+Remember what I told you last week.
+@REMEMBER what I told you last week
+
+(retrieval: "similar to" -> vector)
+Find messages that feel like the argument we had.
+@SIMILAR the argument we had
+
+(retrieval: direct question about named entity -> synthesized answer)
+Where does Maria work?
+@ANSWER where does Maria work
+
+(retrieval: personal-fact question -> @ANSWER, NOT @RECALL)
+Which city did I move to last year?
+@ANSWER which city did I move to last year
+
+(retrieval: personal-fact question -> @ANSWER)
+What is my favorite color?
+@ANSWER what is my favorite color
+
+(walk: "connected" / "linked" BETWEEN NAMED entities - note prefixed anchor)
+How is Nikhil linked to Stripe?
+@RECALL ent:nikhil
+
+(path between two anchors)
+Path from Nikhil to Stripe.
+@PATH ent:nikhil ent:stripe
+
+(common neighbors)
+What do Nikhil and Maria have in common?
+@COMMON ent:nikhil ent:maria