AI memory system for coding agents. Code index + cognitive facts, persistent across sessions.
index1 tested in real-world Claude grep! Comparison of index1 + Claude grep vs Claude grep only:
index1-ab-test.mp4
index1 gives AI coding agents persistent memory — two things LLMs lack natively:
| Module | Memory Type | What it stores |
|---|---|---|
| corpus/ | Semantic memory | Code index — files, functions, classes, structure |
| cognition/ | Episodic memory | Cognitive facts — lessons learned, bug root causes, decisions made |
index1/
├── corpus/ Code index — what does the project look like?
└── cognition/ Cognitive facts — what did I learn last session?
One-click (recommended):
# macOS / Linux
curl -sSL https://raw.githubusercontent.com/gladego/index1/main/scripts/install.sh | bash
# Windows (PowerShell)
irm https://raw.githubusercontent.com/gladego/index1/main/scripts/install.ps1 | iexThe script auto-detects Python, installs via pipx, sets up Ollama, and creates default config.
Manual install:
pipx install index1 # recommended
# or: pip install index1Note: macOS blocks global
pip installby default. Use pipx instead:
- macOS:
brew install pipx- Linux:
pip install --user pipx && pipx ensurepath- Windows:
scoop install pipxorpip install --user pipx
index1 setup # one-click Claude Code plugin install (hooks + MCP)
index1 index ./docs ./src # index your project
index1 search "how does auth work" # hybrid search
index1 web # open Web UI at localhost:6888No Ollama required — index1 ships with built-in ONNX embedding (bge-small-en-v1.5, 384d). Ollama is optional for enhanced multilingual support.
One-click setup (recommended):
index1 setupThis automatically registers hooks (SessionStart, PostToolUse, SessionEnd) and MCP server. Restart Claude Code — six tools become available:
| Tool | Description |
|---|---|
recall |
Unified search across code + facts |
learn |
Record an insight or decision |
read |
Read file content with index metadata |
status |
Index and cognition statistics |
reindex |
Rebuild project index |
config |
View/modify configuration |
Manual setup — add .mcp.json to your project root:
{
"mcpServers": {
"index1": {
"type": "stdio",
"command": "index1",
"args": ["serve"]
}
}
}Full setup guide: Claude Code integration — MCP config, hooks, search strategy, CLAUDE.md setup
MCP-compatible tools: Add the same .mcp.json config above to your tool's MCP settings.
CLI mode (works with any tool):
index1 search "how does authentication work"
index1 cog search "previous bug fixes"Full setup guide: Other AI agents integration
# Core
index1 index <paths...> # Index files/directories
index1 search <query> # Hybrid search (BM25 + vector)
index1 status # View index & cognition statistics
index1 serve # Start MCP Server (stdio)
index1 web # Start Web UI (port 6888)
# Cognition
index1 cog search <query> # Search cognitive facts
index1 cog list # List recent facts
index1 cog stats # Cognition statistics
# Setup & Maintenance
index1 setup # Install Claude Code plugin (hooks + MCP)
index1 doctor # Diagnose environment & health
index1 init # Configure embedding backend
index1 config [key] [value] # View/modify configuration
# Advanced
index1 watch <paths...> # Watch files for auto-reindex
index1 backfill # Backfill missing vectors
index1 repo-map # Generate project structure map
index1 symbols # View symbol statisticsindex1 supports multiple embedding backends with automatic fallback:
ONNX (default, built-in) → Ollama (optional) → BM25-only (always available)
| Backend | Model | Dim | Setup | Best for |
|---|---|---|---|---|
| ONNX (default) | bge-small-en-v1.5 | 384 | Zero config | English, works offline, no external deps |
| Ollama | nomic-embed-text | 768 | ollama pull nomic-embed-text |
Multilingual, higher accuracy |
| Ollama | bge-m3 | 1024 | ollama pull bge-m3 |
Chinese-optimized, 100+ languages |
Switch backend:
index1 init # interactive backend selection
# or manually:
index1 config embed_backend ollama
index1 config embedding_model nomic-embed-textWithout any embedding backend, index1 falls back to BM25-only keyword search. ONNX is bundled by default so vector search works out of the box.
Structure-aware chunking (language-specific parsers):
.md .markdown — headings-based splitting
.py — AST-based (functions, classes, methods)
.rs — regex pattern matching (fn, impl, struct, enum)
.js .ts .jsx .tsx — regex pattern matching (function, class, const)
Generic chunking (text-based splitting):
.txt .text .yaml .yml .toml .json .cfg .ini .conf .sh .bash .html .css
┌─────────────────────────────────────┐
│ index1 MCP Server │
Claude Code ──────► │ │
(hooks + │ ┌─────────┐ ┌──────────────┐ │
MCP tools) │ │ corpus │ │ cognition │ │
│ │ │ │ │ │
CLI ────────────► │ │index.db │ │cognitive.db │ │
│ │ FTS5 │ │ FTS5 │ │
Web UI ─────────► │ │ vec │ │ vec │ │
│ └────┬────┘ └──────┬───────┘ │
│ │ │ │
│ └───────┬───────┘ │
│ │ │
│ ONNX / Ollama Embedding │
└─────────────────────────────────────┘
Hooks:
SessionStart → awaken (restore context)
PostToolUse → observe (capture facts from tool output)
SessionEnd → reflect (maintenance + consolidation)
- Storage: Dual SQLite databases —
index.db(corpus) +cognitive.db(cognition) - Search: BM25 + vector with Reciprocal Rank Fusion (RRF, k=60)
- Chunking: Structure-aware splitting by file type (AST/regex/headings)
- Embedding: ONNX (default, built-in) or Ollama (optional, multilingual)
- Resilience: safe_db_write, CircuitBreaker, ServiceCooldown, mcp_error_boundary
Config file: ~/.claude-index1/config.yaml
embed_backend: onnx # "onnx" (default) | "ollama"
onnx_model: BAAI/bge-small-en-v1.5 # ONNX model
embedding_model: nomic-embed-text # Ollama model (when embed_backend=ollama)
embedding_dim: 768
ollama_url: http://localhost:11434
top_k: 10 # Results per query
collection: default # Namespace isolation
web_port: 6888 # Web UI portProject-level override: .index1.yaml in project root.
Environment variable: INDEX1_HOME overrides default ~/.claude-index1/ directory.
| Mode | Cold | Hot (cached) |
|---|---|---|
| Hybrid (BM25 + Vector) | 40–180 ms | < 1 ms |
| BM25-only (no embedding) | ~35 ms | < 1 ms |
| Grep/Glob (native) | 4 ms | N/A |
Context savings: index1 returns top-k ranked results (~400–500 tokens) vs Grep returning all matches (~5,000–35,000 tokens for common keywords). Saves 90–99% of LLM context window on broad queries.
Full benchmark: Benchmark: index1 vs native tools (中文)
Do I need Ollama? No. index1 v2 ships with built-in ONNX embedding — vector search works out of the box. Ollama is optional for enhanced multilingual and Chinese support.
Can I use multiple projects?
Yes. Use --collection to isolate namespaces:
index1 index ./project-a -c proj_a
index1 search "query" -c proj_aWith Claude Code hooks, collection is auto-detected from project directory.
Where is data stored?
- Corpus:
~/.claude-index1/index.db - Cognition:
~/.claude-index1/cognitive.db - Config:
~/.claude-index1/config.yaml
Override with INDEX1_HOME environment variable.
How to rebuild the index?
index1 index --force ./docs ./srcHow to check system health?
index1 doctorgit clone https://github.com/gladego/index1.git
cd index1
pip install -e ".[dev]"
pytestPRs welcome. Please ensure pytest passes before submitting.
- Cognition module — episodic memory with cognitive facts (learn, recall, maintenance)
- Dual database — separate index.db (corpus) + cognitive.db (cognition)
- ONNX default embedding — built-in bge-small-en-v1.5, zero external deps for vector search
- Claude Code plugin system —
index1 setupone-click install (hooks + MCP) - 6 MCP tools — recall, learn, read, status, reindex, config (unified search across code + facts)
- Hook-based fact capture — SessionStart/PostToolUse/SessionEnd automatic observation
- Memory layering — Ebbinghaus decay, layer promotion (L3b → L3a → L2), pattern extraction
- Maintenance pipeline — 10-step background consolidation (embedding, dedup, decay, invalidation)
- Observer Worker — persistent LLM observer for deep fact extraction
- Web UI — dashboard with corpus, cognition, and memory tabs
- Resilience — safe_db_write, CircuitBreaker, ServiceCooldown, mcp_error_boundary
- Query understanding — intent detection, symbol lookup, query expansion
- tree-sitter code graph — repo-map with symbol extraction
- BM25 + vector hybrid search with RRF fusion
- Structure-aware chunking (Markdown, Python, Rust, JS/TS)
- MCP Server with 5 tools for Claude Code integration
- Web UI with Atom Core animated logo
- L1/L2 query cache (10min TTL)
- File watcher for auto-reindex
- One-click install script
- Python >= 3.10
- macOS / Linux / Windows
- ONNX embedding built-in (bge-small-en-v1.5) — vector search works out of the box
- Ollama (optional, for enhanced multilingual/CJK support)