Manage long-term knowledge memory via Archon RAG. Ingest project documentation, search semantically across projects, sync after changes, manage shared cross-project knowledge, and coordinate tasks. Use when the user says "archon", "knowledge base", "ingest docs", "search docs", "sync docs", or needs deep project context beyond what MEMORY.md provides.
Bridges Claude Code's native memory with Archon's RAG knowledge base for semantic search across unlimited documentation, cross-project knowledge sharing, and multi-agent collaboration.
Invocation: /archon-memory [mode] [arguments]
Examples:
/archon-memory — Status overview + freshness check/archon-memory ingest — Ingest project docs into Archon/archon-memory ingest docs/ — Ingest from specific directory/archon-memory sync — Re-ingest changed docs/archon-memory search subscription gates — Search project knowledge/archon-memory search-all firebase auth patterns — Search all projects/archon-memory shared add https://firebase.google.com/docs — Add shared knowledge/archon-memory shared list — List shared knowledge sources/archon-memory ecosystem — Show all ecosystem projects' Archon status/archon-memory tasks/archon-memory forget — Remove project from ArchonRun this before every operation.
health_check()
If Archon is down or api_service is false:
"Archon server is not reachable. Check that it's running on the configured host. The archon MCP server must be configured in .mcp.json or ~/.claude/mcp.json."
Stop here if unhealthy.
Read .claude/archon-state.json. If last_extension_sync is missing or older than 24 hours:
"Extensions are out of sync. Running extension sync first..."
Run /archon-extension-sync before continuing.
Read these if they exist (don't fail if missing — some modes create them):
.claude/archon-state.json in the current project~/.claude/archon-global.json| Argument | Mode |
|---|---|
(none) or status | STATUS |
ingest [dir] | INGEST |
sync | SYNC |
search <query> | SEARCH (project-scoped) |
search-all <query> | SEARCH-ALL (unscoped) |
shared add <url> | SHARED-ADD-URL |
shared add-docs <dir> | SHARED-ADD-DOCS |
shared search <query> | SHARED-SEARCH |
shared list | SHARED-LIST |
tasks | TASKS-LIST |
task create <title> | TASK-CREATE |
task update <id> <status> | TASK-UPDATE |
project | PROJECT-INFO |
ecosystem | ECOSYSTEM |
forget | FORGET |
First-time ingestion of project documentation into Archon.
git remote get-url origin 2>/dev/null || echo "no-remote"
Get the project directory name as fallback:
basename $(git rev-parse --show-toplevel 2>/dev/null || pwd)
Check if an Archon project already exists for this repo:
find_projects(query="<repo-name>")
If found: Use the existing project. Extract project_id.
If not found: Create one:
manage_project(action="create", title="<repo-name>", github_repo="<remote-url>")
Save the project_id.
If .claude/archon-state.json already exists with a source_id: Warn the user:
"This project already has docs in Archon (source: src-xxx, synced <date>). Running ingest again will create a duplicate. Use
/archon-memory syncto update instead, or/archon-memory forgetfirst to start fresh."
Stop unless the user explicitly wants to proceed.
Scan for documents to ingest:
Primary directory: All .md files in docs/ (or user-specified directory)
Glob: docs/**/*.md (or <specified-dir>/**/*.md)
Extra files: Look for these in the project root and parent directory:
CLAUDE.mdREADME.mdCLAUDE.md (e.g., ../CLAUDE.md for monorepo setups)Exclude: Skip any files matching:
node_modules/.git/Report discovery to user:
"Found X documents to ingest:
- docs/ : Y files
- CLAUDE.md: found
- README.md: found Total: ~Z KB. Proceed?"
Wait for user confirmation.
For each discovered file:
Check the file's line count:
wc -l <filepath> | awk '{print $1}'
Read the full file content:
offset and limit parameters, then concatenate all chunks into the complete content string:
Read(file_path=<filepath>, limit=1500) # lines 1–1500
Read(file_path=<filepath>, offset=1500, limit=1500) # lines 1501–3000
Read(file_path=<filepath>, offset=3000, limit=1500) # lines 3001–4500
# ... continue until offset ≥ total line count
Strip the line-number prefix from each chunk (format: N→) before concatenating.CRITICAL: Never use the Read tool without limit on a file before confirming it is ≤ 1500 lines. The default 2000-line limit silently truncates larger files, resulting in partial indexing.
Compute MD5 hash of the content:
md5sum <filepath> 2>/dev/null | cut -d' ' -f1 || md5 -q <filepath> 2>/dev/null
Add to documents array:
{"title": "<filename>", "content": "<full content>", "path": "<relative path>"}
Use sub-agents to read files in parallel batches for speed (groups of 5-10 files). Each sub-agent must follow the line-count check and chunked reading steps above.
manage_rag_source(
action="add",
source_type="inline",
title="<repo-name> Documentation",
documents=<documents array as list>,
tags=["<repo-name>", "project-docs"],
project_id="<archon-project-id>",
knowledge_type="technical",
extract_code_examples=true
)
Important: Pass documents as a native list, not a JSON string. Archon accepts both formats (fixed in commit 8337ec3).
Save progress_id and source_id from the response.
rag_check_progress(progress_id="<progress_id>")
Poll every 5 seconds. Report progress:
"Ingesting... 19/42 documents processed (45%)"
Continue until status is "completed", "failed", or "error".
If failed: Report the error details and stop. Suggest checking Archon server logs.
If progress_id returns 404: The operation completed and progress data expired (~30s TTL). Check rag_get_available_sources() to verify the source was created.
Run a test search to confirm content is indexed:
rag_search_knowledge_base(
query="project architecture overview",
project_id="<archon-project-id>",
match_count=3
)
If results are returned, ingestion is confirmed working.
7a. Write .claude/archon-state.json:
{
"archon_project_id": "<project-id>",
"archon_project_title": "<repo-name>",
"git_remote": "<remote-url>",
"sources": {
"project-docs": {
"source_id": "<source-id>",
"title": "<repo-name> Documentation",
"last_synced": "<ISO timestamp>",
"doc_count": <number>,
"directories": ["docs/"],
"extra_files": ["CLAUDE.md", "README.md"],
"file_hashes": {
"<relative-path>": "<md5-hash>",
...
}
}
},
"created_at": "<ISO timestamp>"
}
7b. Ensure .claude/archon-state.json is in .gitignore:
grep -q "archon-state.json" .gitignore 2>/dev/null || echo ".claude/archon-state.json" >> .gitignore
7c. Update MEMORY.md — add or update an "Archon Knowledge Base" section:
## Archon Knowledge Base
- Project ID: <project-id>
- Source: "<repo-name> Documentation" (<source-id>), <N> docs, synced <date>
- Search: `rag_search_knowledge_base(query="...", project_id="<project-id>")`
## Archon Memory — Ingestion Complete
**Project:** <repo-name>
**Archon Project ID:** <project-id>
**Source ID:** <source-id>
**Documents ingested:** <count>
**Chunks stored:** <from progress results>
**Code examples extracted:** <from progress results>
### What's indexed
- docs/ (<N> files covering: <brief topic summary>)
- CLAUDE.md: project instructions
- README.md: project overview
### How to use
- `/archon-memory search <query>` — search this project's knowledge
- `/archon-memory search-all <query>` — search all projects
- `/archon-memory sync` — re-sync after doc changes
- `/archon-memory status` — check freshness
If any files required chunked reading (> 1500 lines), confirm in the report that all chunks were fully read and the complete content was indexed — do NOT note truncation.
Re-ingest project docs after changes. Uses delete + re-add since Archon inline sync is not reliable.
Read .claude/archon-state.json.
If missing:
"No Archon state found for this project. Run
/archon-memory ingestfirst."
md5sum <filepath> 2>/dev/null | cut -d' ' -f1 || md5 -q <filepath> 2>/dev/null
Report:
"Changes detected since last sync (<date>):
- Modified: 3 files
- Added: 1 file
- Removed: 0 files Proceed with re-sync?"
If no changes detected:
"All documents are up to date. Last synced: <date>."
Warning: Sync uses delete + re-add, which means there's a brief window where the knowledge base has no content for this project. If the delete succeeds but re-add fails, run /archon-memory ingest to recover.
Re-read all docs first (same as Ingest Phase 3) — read BEFORE deleting to ensure content is ready
Delete old source:
manage_rag_source(action="delete", source_id="<old-source-id>")
Re-ingest immediately (same as Ingest Phase 4):
manage_rag_source(action="add", ...)
Poll for completion (same as Ingest Phase 5)
.claude/archon-state.json with new source_id, timestamp, and hashes
(source_id changes on every delete + re-add)Report:
"Sync complete. <N> documents re-ingested. New source ID: <source-id>."
Semantic search across ingested documentation.
search <query> (project-scoped)rag_search_knowledge_base(
query="<query>",
project_id="<archon-project-id>",
match_count=5,
return_mode="pages"
)
Get archon_project_id from .claude/archon-state.json. If state file is missing, check Archon directly:
find_projects(query="<repo-name>")
search-all <query> (unscoped)rag_search_knowledge_base(
query="<query>",
match_count=10,
return_mode="pages"
)
No project_id — searches across all projects and shared knowledge.
Show as a table:
## Search Results for "<query>"
| # | Section Title | Similarity | Words | Chunks | Source ID |
|---|--------------|------------|-------|--------|-----------|
| 1 | subscriptions.md | 0.89 | 1,250 | 3 | src-xxx |
| 2 | userLogic.md | 0.72 | 3,400 | 5 | src-xxx |
Then ask:
"Want me to read the full content of any of these pages?"
If yes, use:
rag_read_full_page(page_id="<page-id-from-results>")
Also search for code examples:
rag_search_code_examples(
query="<query>",
project_id="<archon-project-id>",
match_count=3
)
If code results found, show them below the page results.
Default mode when /archon-memory is called with no arguments.
Read .claude/archon-state.json. If missing:
"No Archon state found for this project. Run
/archon-memory ingestto get started."
Query Archon to verify source still exists:
rag_list_pages_for_source(source_id="<source-id>")
Read ~/.claude/archon-global.json for shared knowledge info.
## Archon Memory Status
**Project:** <repo-name> (<project-id>)
**Source:** <source-title> (<source-id>)
**Last synced:** <date> (<relative time>)
**Documents:** <N> indexed
**Freshness:** <N> files changed since last sync
- <filepath> (modified|added|removed)
- ...
**Shared Knowledge:** <N> sources
- <source-title> (<source-id>)
- ...
**Suggestion:** <action based on state>
Suggestions:
/archon-memory sync to update."/archon-memory ingest to re-create."Manage cross-project shared knowledge. Uses a dedicated "Shared Knowledge Base" project in Archon.
shared add <url> — Add URL-based shared knowledgeGet or create shared project:
~/.claude/archon-global.json for shared_project_idmanage_project(action="create", title="Shared Knowledge Base",
description="Cross-project knowledge accessible from any project")
shared_project_id to ~/.claude/archon-global.jsonIngest the URL:
manage_rag_source(
action="add",
source_type="url",
title="<extracted domain or user label>",
url="<url>",
project_id="<shared-project-id>",
tags=["shared", "<domain>"]
)
Poll for completion via rag_check_progress
Update ~/.claude/archon-global.json with new source entry
shared add-docs <dir> — Add local docs as shared knowledgeSame as project ingest flow, but targets the shared knowledge project instead of the current project's Archon project.
shared search <query>rag_search_knowledge_base(
query="<query>",
project_id="<shared-project-id>",
match_count=5
)
shared listrag_get_available_sources()
Filter results to sources whose source_id matches entries in ~/.claude/archon-global.json.
Display:
## Shared Knowledge Sources
| # | Title | Source ID | Pages | Last Synced |
|---|-------|----------|-------|-------------|
| 1 | Firebase Documentation | src-xxx | 1,200 | 2026-03-01 |
| 2 | Next.js Documentation | src-yyy | 800 | 2026-03-01 |
Manage Archon project tasks for multi-agent coordination.
tasks — List tasksfind_tasks(project_id="<archon-project-id>")
Display grouped by status:
## Project Tasks
### Doing
- [task-id] Task title (assignee)
### To Do
- [task-id] Task title
### Review
- [task-id] Task title (assignee)
### Done
- [task-id] Task title
task create <title>manage_task(action="create",
project_id="<archon-project-id>",
title="<title>",
status="todo",
assignee="User"
)
Report: "Task created: <title> (ID: <task-id>)"
task update <id> <status>Valid statuses: todo, doing, review, done
manage_task(action="update", task_id="<id>", status="<status>")
Report: "Task <id> updated to <status>."
View or manage the Archon project for the current repo.
If .claude/archon-state.json is missing:
"No Archon project linked to this repo. Run
/archon-memory ingestto create one, or usemanage_projectmanually."
find_projects(project_id="<archon-project-id>")
Display project details including title, description, github_repo, features.
Show status of all RecipeRaiders ecosystem projects in Archon. No arguments needed.
Read ~/.claude/archon-global.json. If missing:
"No ecosystem configuration found. Run
/archon-memory ingestin each project first, or set up the ecosystem via the multi-project rollout process."
For each project in ecosystem_projects:
find_projects(project_id="<project-id>")
Also check the shared knowledge project:
find_projects(project_id="<shared-project-id>")
If the current working directory matches one of the ecosystem projects, read its .claude/archon-state.json and run a freshness check (compare file hashes).
## RecipeRaiders Ecosystem — Archon Status
### Shared Knowledge
| Source | Docs | Last Synced | Status |
|--------|------|-------------|--------|
| RecipeRaiders Ecosystem Documentation | 2 | <date> | <fresh/stale> |
### Projects
| Project | Archon ID | Docs | Last Synced | Status |
|---------|-----------|------|-------------|--------|
| RecipeRaiders (main) | 2d747998... | 51 | <date> | <fresh/stale/unknown> |
| reciperaiders-spa | d452583d... | 2 | <date> | <fresh/stale/unknown> |
| reciperaiders-repdash | 9b18cc38... | 3 | <date> | <fresh/stale/unknown> |
| RecipeRaiders-Marketing | 5ba91517... | 2 | <date> | <fresh/stale/unknown> |
### Current Project: <name>
<Freshness details if available>
Status values:
/archon-memory syncBased on ecosystem state, suggest:
/archon-memory sync in <project-dir> to update."/archon-memory shared sync to update ecosystem docs."/archon-memory ingest in <project-dir> to set up."Remove all project knowledge from Archon.
"This will permanently remove all project documentation from Archon's knowledge base. The Archon project and tasks will be preserved unless you also want to delete those. Proceed?"
Wait for explicit user confirmation.
manage_rag_source(action="delete", source_id="<source-id>")
Ask:
"Also delete the Archon project (removes tasks, documents, versions too)?"
If yes:
manage_project(action="delete", project_id="<archon-project-id>")
.claude/archon-state.jsonReport: "Project knowledge removed from Archon."
"subscription gates", "firebase auth", "deploy staging""how do subscription gates work in the payment system for premium users".claude/archon-state.json (gitignored, created by ingest)~/.claude/archon-global.json (shared knowledge registry)rag_get_available_sources() to verifyAll Archon data is shared across agents. When this Claude Code instance ingests or modifies data, other agents (Cursor, Windsurf, other Claude instances) see the changes immediately. Use Archon tasks for coordinating work across agents.