Talamus Memory

use the talamus CLI to maintain source-grounded markdown memory backed by a derived local sqlite/fts5 index. keep the brain inspectable, preserve citations, and make all potentially paid or sensitive operations explicit.

Intent

this skill sets up talamus as a local-first memory system for ai agents. use it to initialize a talamus brain (project or global), ingest files and repositories, retrieve cited context without hallucination, inspect note history and provenance, verify memory against sources, review and apply corrections, connect agents through mcp, and optionally capture session decisions. the skill prioritizes safety by making all llm calls and mutations explicit, requiring consent before expensive operations, and preserving citations so memory claims stay grounded.

Inputs

talamus CLI

• executable: talamus (installed via uv tool, pipx, or pip --user; check with talamus --version)
• version: any stable release with mcp, ingest, verify, and review commands

brain location and scope

• project brain: initialized at project root via talamus setup or talamus init
• global brain: initialized at user home or os-specific data directory
• optional scope flags: --scope project+central, --all-brains

external data sources (optional; requires consent before ingestion)

• local files and directories (markdown, plain text, json, yaml, code)
• git repositories (source code, docs, commit history; previewed with --dry-run)
• markdown, obsidian, or notion export vaults (lossless import mode)
• urls for single-source ingestion (http/https accessible)

environment and credentials (if talamus integrations are enabled)

• talamus config file: talamus.json in project or home directory (never expose secrets from this file)
• mcp agent credentials: installed separately per agent (claude, cursor, codex, opencode, openclaw)
• session capture hook: installed only with explicit --capture yes consent

network and rate limits (edge cases)**

• llm calls (via ask, search --smart, ingest, enrich, consolidate, verify without --stale) may hit rate limits or timeouts; plan for retry or degradation to lexical search
• talamus doctor may detect stale indexes, capture queue backlog, or source validation failures
• repository scans with --allow-secrets require explicit approval and are high-risk operations

Procedure

step 1: inspect readiness and brain location

1.1. inputs: shell access, talamus executable (may be missing) 1.2. run talamus --version to check if executable is on path 1.3. if missing, explain the installation approach (uv, pipx, or pip) and ask once before proceeding 1.4. run talamus where to confirm the active brain path (must be unambiguous; abort if ambiguous) 1.5. run talamus status to check if the brain is initialized, healthy, index state, and last activity 1.6. run talamus doctor to detect missing indexes, capture queue issues, source validation errors, or mcp problems 1.7. output: active brain path, version, health status, any diagnostics

step 2: retrieve from memory deterministically (no llm calls unless approved)

2.1. inputs: query or question, optional scope flags (--scope project+central, --all-brains) 2.2. for lexical retrieval (no embeddings, no llm), run talamus search "QUERY" --json 2.3. for qa-style retrieval, run talamus recall "QUESTION" --json 2.4. for a specific note, run talamus read "NOTE TITLE" --json 2.5. if lexical retrieval is insufficient, inform the user that search --smart will call an llm and ask for consent 2.6. if approved, run talamus search "QUERY" --smart --json 2.7. for a cited synthesis with trace, run talamus ask "QUESTION" --trace (inform user this is an llm call; get consent first) 2.8. for historical questions, run talamus ask "QUESTION" --as-of YYYY-MM, talamus timeline "NOTE TITLE", or talamus history "NOTE TITLE" (preserve time boundary) 2.9. output: retrieved notes in json, citations (source file, line numbers), relevance scores where available, trace log if --trace was used

step 3: add knowledge deliberately (ingest and import)

3.1. inputs: file path, directory, url, or vault path; optional flags (--dry-run, --profile, --allow-secrets) 3.2. for a single source (file, url, or small directory), summarize the scope and inform user that ingest may call an llm to summarize or extract structure; get consent 3.3. run talamus ingest PATH_OR_URL (llm call if content is large or complex; preview the summary before confirmation) 3.4. for a repository, run talamus scan . --dry-run --profile PROFILE (e.g. docs, code, all) to preview files and estimate llm usage 3.5. show the user the plan: files to ingest, estimated notes, any sensitive patterns detected 3.6. if --allow-secrets is requested, require explicit approval before proceeding; warn that secrets may be exposed if ingested 3.7. after approval, run talamus scan . --yes --profile PROFILE 3.8. for an existing markdown, obsidian, or notion vault (lossless import), run talamus import-vault PATH (no llm calls) 3.9. after a write, report: target brain path, sources processed, notes created/updated, review items created, skipped or failed inputs 3.10. output: json log of ingestion results, note titles, source mappings

step 4: verify provenance and curate memory

4.1. inputs: optional note title, review item id 4.2. for stale-check (no llm), run talamus verify --stale --json 4.3. list all pending review items with talamus review list --json 4.4. show a specific review proposal with talamus review show ID --json 4.5. if user requests verification with llm (fact-check), inform them and get consent; run talamus verify "NOTE TITLE" (llm call) 4.6. preview the verification result and any proposed corrections; do not apply automatically 4.7. if user approves a review item, run talamus review apply ID; if rejected, run talamus review reject ID --reason "REASON" 4.8. if user approves a verification correction, run talamus verify "NOTE TITLE" --apply 4.9. after manual note edits (e.g. in editor), run talamus reindex to update the index 4.10. if index, engine, capture queue, or source validation behaves unexpectedly, run talamus doctor again 4.11. output: review items shown, decisions applied, notes updated, reindex result

step 5: connect agents via mcp (optional)

5.1. inputs: optional agent target (--agent claude, cursor, codex, opencode, openclaw, auto, or all) 5.2. install mcp configuration only when the user explicitly requests agent connection 5.3. run talamus mcp install --agent auto (detects common agents) or specify target agent 5.4. after install, run talamus doctor to verify mcp integration 5.5. report which agents were detected and connected (claude, cursor, codex, opencode, openclaw) 5.6. note: openclaw receives a read-oriented tool filter by default; llm-backed and mutating tools (ingest, review apply) require explicit opt-in 5.7. output: mcp installation log, detected agents, tool availability per agent

step 6: optional session capture (requires explicit consent)

6.1. inputs: user consent via prompt or flag 6.2. explain that session capture reads the current session transcript and git diff, stores decisions locally, and audits the decision for transparency 6.3. never install a session-capture hook without explicit consent; prefer talamus setup --capture ask (asks at setup time) 6.4. if user requests capture, run talamus setup --capture yes or the dedicated hook command 6.5. after install, verify with talamus doctor 6.6. output: hook installation log, transcript location, audit log path

step 7: back up before risky maintenance

7.1. inputs: none (routine before destructive operations) 7.2. before bulk curation, relocation, or destructive maintenance (e.g. bulk delete, schema migration), create a portable backup 7.3. run talamus export brain.zip (creates a complete snapshot of notes, sources, index, and metadata) 7.4. report backup file size and path 7.5. output: backup file location, checksum

step 8: summarize and advise next action

8.1. inputs: all prior steps 8.2. report the active brain path, commands actually run, any llm or capture activity, evidence retrieved or changed 8.3. advise the safest next action (e.g. "review 3 pending items before ingesting more", "run doctor if ingest stalled", "create backup before verify --apply") 8.4. output: summary log, recommended next step

Decision Points

if talamus executable is missing

• propose installation via uv tool install "talamus[mcp]" (preferred if uv is available)
• else propose pipx install "talamus[mcp]" (if pipx is available)
• else propose python -m pip install --user "talamus[mcp]" (last resort)
• ask for consent before installing; never install silently
• after install, verify with talamus --version and report the bin directory if path is wrong
• do not run multiple installers for the same skill

if brain location is ambiguous

• run talamus where and stop if multiple brains are detected
• ask the user to clarify: is this a project brain (at project root) or global brain (at home/data dir)?
• only proceed after user confirms the target brain

if no brain exists

• ask whether memory should be scoped to this project or be global
• for project brain, run talamus setup --capture ask from project root (enables mcp and session capture prompting)
• for global brain, run talamus init (minimal init, no mcp or hook)
• for any brain, offer to explain the difference and storage location before initializing

if lexical retrieval returns no results or low confidence

• inform user that search --smart will call an llm to embed the query and find semantic matches
• ask for consent before running search --smart
• if user declines, suggest rephrasing the lexical query or reviewing existing notes manually

if a single ingest or repository scan is requested

• for a single file/url, summarize the content and ask if user wants talamus to call an llm to extract structure/summary
• for a repository, run --dry-run and show the file list and estimated llm usage
• ask for approval of the plan before running the real ingest
• if --allow-secrets is requested, warn that secrets may be extracted and stored; require explicit approval

if review items or verification corrections are proposed

• always show the proposal to the user (via talamus review show ID or verification output)
• do not apply, reject, or consolidate automatically
• ask the user to approve or reject each item before running review apply or review reject

if session capture is requested

• explain that the hook reads the session transcript and git diff, stores decisions, and creates an audit log
• require explicit consent via --capture yes (not --capture ask, which only prompts at setup time)
• never install a hook silently or without clear explanation of what is captured

if mcp connection is requested

• install only when the user explicitly asks; do not install proactively
• use --agent auto to detect common agents, or specify the target agent
• warn that openclaw has read-only tools by default; mutating tools require opt-in
• run doctor after install to verify integration

if talamus doctor reports stale indexes, capture queue backlog, or source validation errors

• report the diagnostic findings to the user
• suggest remediation: reindex, clear capture queue, re-run source validation, or ask for more details
• do not proceed with writes or verification until critical issues are resolved

if a network timeout, rate limit, or llm call failure occurs

• report the error and suggest retry or fallback (e.g. switch to lexical search)
• for persistent errors, suggest talamus doctor to diagnose connectivity or service health
• inform the user of any partial results (e.g. some notes retrieved, some ingestion skipped)

Output Contract

readiness check (step 1)

• stdout: talamus version, active brain path (from talamus where), status summary (initialized, index age, last activity), doctor diagnostics (errors, warnings)
• format: text or json (if --json is passed)
• file location: none (diagnostic output only)

retrieval (step 2)

• stdout: retrieved notes in json format (title, body, source file, line ranges, citation markers)
• optional: trace log (if --trace was used) showing which sources and embeddings were consulted
• format: json (from --json flags) or formatted text
• file location: none (streamed to stdout)

ingestion (step 3)

• stdout: ingestion log (sources processed, notes created/updated, review items, failures)
• format: json or text summary
• file location: talamus database (.talamus/ directory in brain root); notes are stored as markdown with source citations
• side effects: new notes added to the brain, review items queued if corrections are needed

verification and curation (step 4)

• stdout: review items shown (id, proposed change, rationale), verification result (fact-check pass/fail, corrections)
• format: json (from --json) or formatted text
• file location: review items stored in talamus database; applied corrections update the note files
• side effects: notes updated, review items removed after apply/reject

mcp integration (step 5)

• stdout: mcp install log, detected agents, tool availability per agent
• format: text
• file location: mcp config written to agent config directories (e.g. ~/.config/claude/mcp.json)
• side effects: talamus tools now available in connected agents

session capture (step 6)

• stdout: hook install log, transcript location, audit log location
• format: text
• file location: hook script installed in .talamus/hooks/; transcripts stored in .talamus/captures/
• side effects: subsequent sessions are captured with consent

backup (step 7)

• stdout: backup file path, size, checksum
• format: text
• file location: brain.zip in current directory (or user-specified path)
• side effects: none (read-only backup)

summary and next action (step 8)

• stdout: active brain path, list of commands run, llm calls made, data modified, recommended next step
• format: text
• file location: none (summary output)

Outcome Signal

the user knows the skill worked when:

1. readiness check succeeds: talamus where returns an unambiguous brain path, talamus status shows a healthy initialized brain with a current index, and talamus doctor reports no critical errors
2. retrieval returns cited results: talamus search, talamus recall, or talamus read returns json with note titles, bodies, source file paths, line numbers, and citation markers (e.g. [source: file.md:42-50])
3. ingestion completes and notes appear: talamus scan or talamus ingest reports the number of notes created/updated, review items queued, and sources processed; running talamus search on a phrase from the ingested content returns the new note
4. verification and curation are transparent: talamus review list shows pending items, talamus review show ID previews a specific proposal, and talamus review apply or talamus verify --apply updates the note without silent changes
5. mcp agents connect: talamus doctor reports mcp integration success, the agent (claude, cursor, etc.) recognizes talamus tools (search, read, ask, ingest, etc.), and a test query through the agent returns cited results
6. session capture is auditable: .talamus/captures/ contains readable transcript logs, .talamus/hooks/ contains the installed hook script, and talamus doctor confirms the hook is active
7. backup is portable: brain.zip can be extracted on another machine and talamus where points to the restored brain with all notes and indexes intact
8. user confirms the operation: every llm call (ask, search --smart, ingest, verify without --stale, enrich, consolidate, remember), mutation (ingest, review apply, verify --apply), or capture operation is explicitly requested by the user and confirmed before execution; the final summary lists what was actually run and what changed