Stateless Agent Memory Engine (SAME)

Create a session handoff note so the next session picks up where this one left off. Write what you worked on, what's pending, and any blockers.

Args: summary: What was accomplished this session pending: What's left to do (optional) blockers: Any blockers or open questions (optional) agent: Optional writer attribution stored in frontmatter (e.g. 'codex')

Returns path to the handoff note.

Find notes that cover similar topics to a given note. Use this to discover related context, find notes that might conflict, or build a broader picture of a topic.

Args: path: Relative path of the source note top_k: Number of similar notes (default 5, max 100)

Returns list of related notes ranked by similarity.

Read the full content of a note. Use this after search_notes returns a relevant result and you need the complete text. Paths are relative to the vault root.

Args: path: Relative path from vault root (as returned by search_notes)

Returns full markdown text content.

Get orientation context for a new session. Returns pinned notes, the latest handoff, and recent decisions — everything you need to pick up where the last session left off.

Returns structured session context.

Check the health and size of the note index. Use this to verify the index is up to date or to report stats to the user.

Returns note count, chunk count, last indexed timestamp, embedding model info, and database size.

If the user reports problems, suggest they run same doctor for diagnostics. For bugs, direct them to: https://github.com/sgx-labs/statelessagent/issues

Get an orientation briefing of what matters right now. Shows recent activity, open decisions, and key context. Use this at the start of a session to understand current project state.

Args: max_items: Maximum items per section (default 5)

Returns a concise briefing generated from vault contents. (experimental)

Consolidate related notes in the vault. Merges duplicates, resolves contradictions, extracts key facts. Creates new knowledge files without modifying originals. Use this when the vault has many similar or overlapping notes.

Args: dry_run: Preview what would be consolidated without writing files (default false) threshold: Similarity threshold for grouping notes, 0.0-1.0 (default 0.75)

Returns consolidation summary with groups found, facts extracted, and conflicts resolved. (experimental)

Suppress a memory so it won't be surfaced in normal search. The note is not deleted -- it's marked as suppressed and will only appear if explicitly requested. Use this for outdated, incorrect, or irrelevant memories. This is not easily reversible: there is no mem_restore tool.

Args: path: Path of the note to suppress (required) reason: Why this memory is being suppressed (optional)

Returns confirmation of suppression. (experimental)

Check the health of the memory vault. Returns a health score (0-100) and actionable recommendations. Use this to determine if the vault needs consolidation, reindexing, or cleanup.

Returns health score, key metrics, and recommendations. (experimental)

Get recently modified notes. Use this to see what's changed recently or to orient yourself at the start of a session.

Args: limit: Number of recent notes (default 10, max 50)

Returns list of recently modified notes with titles and paths.

Re-scan and re-index all markdown notes. Use this if the user has added or changed notes and search results seem stale. Incremental by default (only re-embeds changed files).

Args: force: Re-embed all files regardless of changes (default false)

Returns indexing statistics.

Log a project decision. Appends to the decision log so future sessions can find it.

Args: title: Short decision title (e.g. 'Use JWT for auth') body: Full decision details — what was decided, why, alternatives considered status: Decision status — 'accepted', 'proposed', or 'superseded' (default 'accepted') agent: Optional writer attribution stored in frontmatter (e.g. 'codex')

Returns confirmation.

Log a friction point, bug, or improvement idea discovered during work. SAME tracks provenance — if the source files change later, the item is automatically flagged as potentially addressed.

Args: description: What was observed (required) area: Area of the codebase (e.g. 'indexer', 'config', 'hooks') (optional) agent: Who observed it (optional) sources: Related file paths for provenance tracking (optional)

Returns confirmation with the file path.

Create or update a markdown note in the vault. The note is written to disk and indexed automatically.

Optionally specify source files to enable provenance tracking — SAME will flag this note as stale if sources change.

Args: path: Relative path within the vault (e.g. 'decisions/auth-approach.md') content: Markdown content to write append: If true, append to existing file instead of overwriting (default false) agent: Optional writer attribution stored in frontmatter (e.g. 'codex') sources: File paths that this note was derived from (optional)

Returns confirmation with the saved path.

Search across multiple registered vaults at once. Use this instead of search_notes when you need context from other projects or want a cross-project view. Vaults must be registered first via the CLI (same vault add <name> <path>).

Args: query: Natural language search query top_k: Number of results (default 10, max 100) vaults: Comma-separated vault aliases to search. Omit to search all registered vaults. Unknown aliases are silently skipped.

Returns ranked results with titles, paths, snippets, and source vault name.

Search the user's knowledge base for relevant notes, decisions, and context. Use this when you need background on a topic, want to find prior decisions, or need to understand project architecture.

Args: query: Natural language search query (e.g. 'authentication approach', 'database schema decisions') top_k: Number of results (default 10, max 100)

Returns ranked list of matching notes with titles, paths, and text snippets.

Search the user's knowledge base with metadata filters. Use this when you want to narrow results by domain (e.g. 'engineering'), workstream (e.g. 'api-redesign'), tags, agent attribution, trust state, or content type.

Args: query: Natural language search query top_k: Number of results (default 10, max 100) domain: Filter by domain (e.g. 'engineering', 'product') workstream: Filter by workstream/project name tags: Comma-separated tags to filter by agent: Filter by agent attribution (e.g. 'codex', 'claude') trust_state: Filter by trust state (validated, stale, contradicted, unknown) content_type: Filter by content type (decision, handoff, note, research)

Returns filtered ranked list.