io.github.sumanaddanki/suma-memory

Wipe all data for this org. DESTRUCTIVE — requires confirmation. Args: confirm: Must be true to proceed (required)

Correct an incorrect node — preserves audit trail, cleans graph. The node is marked as superseded (never deleted), and all its mentions/entities are cleaned. Use this when you find incorrect information in the knowledge graph. Args: node_id: The node ID to correct (required) reason: Why this node is wrong (required) replacement_text: Correct information to ingest (optional)

Add knowledge to the SUMA graph. The engine accepts any form of input — raw conversational paragraphs, verbatim file excerpts, synthesized factual statements, or compressed semantic summaries. K-WIL gravity (cosine² × decay × harmonic_weight) will rank all nodes correctly regardless of ingestion style. How you drive the engine is determined by your use case, not the engine itself. Provenance tip: always populate source_doc and source_page so retrieved nodes can be traced back to the physical file. The engine stores provenance but does not enforce it. Args: text: The compressed knowledge to store (required) sphere: Category - family, work, friends, health, architecture (optional, auto-classified) extract_relationships: Auto-extract entities (default: true) source_doc: Where this came from — file path, URL, or document title (optional) source_section: Chapter, heading, or function name within the document (optional) source_page: Page number (PDF) or line number (code) (optional) source_type: 'manual'|'file'|'pdf'|'url'|'code' (optional, default: manual) Response fields: node_id: ID of the created or reinforced node status: 'created' | 'merged' (merged = near-duplicate detected by Gate 2) similarity: Cosine similarity score against the nearest existing node (0.0–1.0). Only present when status='merged'. harmonic_weight: Updated harmonic weight of the node after Gate 2 Hebbian reinforcement. Near-duplicates strengthen the existing node instead of creating noise. reinforcement: How much harmonic_weight increased this ingest (e.g. 0.05–0.20). Higher for near-identical content. Only present when status='merged'.

Health check — verify connection and org. Call once at session start.

Search the knowledge graph using Gravity Well Algorithm. Phases: 1. Entity Strike — find entity by name 2. Neighborhood Expansion — get relationships 3. Evidence Bridge — get related nodes 4. GIN Fallback — full-text search Args: query: Natural language query (required) limit: Max results (default: 10) sphere: Filter by one sphere, OR pass an array for multi-sphere queries (optional) e.g. "work" or ["work", "personal"] historical_search: Set true ONLY when user explicitly asks for past events, older data, or specific date ranges ("last year", "in 2024", "back in March", "what did I do previously"). Suppresses time decay so old nodes surface correctly. Defaults to false.

Graph statistics and K-WIL token economics for this org. Returns node count, sphere breakdown, queries used, tokens sent vs baseline, compression ratio, and estimated cost saved. The ROI receipt — call this to show the user how much context window budget SUMA has saved them. No arguments needed — reads from the authenticated org.

Bidirectional memory — search AND learn in one call. Searches for relevant context, optionally stores the message as new knowledge. Args: message: User message (required) learn: Store message as knowledge (default: true) sphere: Category for storage (optional)