lybrary

Living structure-aware code memory for AI coding agents.

lybrary indexes your repository with real AST boundaries (functions, classes, methods), keeps the index fresh via a background daemon, and gives AI agents a high-signal memory they can query instead of reading raw files.

This reduces token burn and hallucinations compared to pure agentic search or flat embedding RAG.

Why lybrary?

Current IDE agents either:

• Re-explore the repo with grep/read every session (expensive, amnesiac), or
• Use flat semantic search that doesn't understand code structure.

lybrary sits in the middle:

• AST-aware chunks (cAST-style) — never splits a function in half
• Persistent daemon that auto-updates on every file change
• Hybrid retrieval (vector search + token-budget packing)
• Agent-first design — agents query memory instead of walking the tree
• MCP server — works natively with Kiro, Cursor, Claude Desktop, Windsurf, and any MCP-compatible IDE
• Fully local — no cloud, no API keys, embeddings run on your machine

Quick start

pip install lybrary

cd /path/to/your/repo
lybrary init
lybrary start          # builds index + starts background daemon
lybrary query "authentication flow"

After lybrary start, the daemon keeps running even if you close the terminal. File changes are picked up automatically and only the affected chunks are re-indexed.

MCP integration (AI IDEs)

Add this to your MCP config (works with Kiro, Cursor, Claude Desktop, Windsurf):

{
  "mcpServers": {
    "lybrary": {
      "command": "lybrary",
      "args": ["mcp"]
    }
  }
}

The agent then has three tools available:

Agents should call memory_query before reading any files. This replaces multi-file reads with a single targeted query, cutting token usage by 80–90% on large codebases.

CLI

How chunking works

1. Detect language from file extension
2. Parse with tree-sitter
3. Extract definition nodes (functions, classes, methods, interfaces, impls…)
4. Container nodes (classes, impls) emit as a chunk and recurse so nested methods get their own chunks
5. Attach rich metadata + a context header used for embedding
6. Fall back to careful line-based splitting only when a grammar is missing

Supported languages: Python, JavaScript, TypeScript, TSX, Go, Rust, Java, C, C++.

Architecture (v0.1)

.lybrary/
├── config.toml
├── index.db          # SQLite: chunks + vectors (numpy float32 blobs)
├── file_hashes.json  # content-hash map for incremental updates
├── daemon.pid
└── daemon.log

• Indexer: tree-sitter → AST chunks → local embeddings (fastembed / all-MiniLM-L6-v2, ONNX Runtime)
• Store: SQLite + numpy (cosine similarity via batched dot product)
• Daemon: watchdog file watcher + debounce + incremental re-chunk/embed
• Query: vector search + token-budget packing
• MCP: FastMCP server over stdio

Roadmap

• AST chunker (multi-language, cAST-style)
• Incremental indexing via content hashes
• Background daemon + file watcher (Windows + Unix)
• CLI (init/start/stop/status/index/query/logs/mcp)
• MCP server (memory_query, memory_status, memory_update)
• Call/import graph + expansion
• Hierarchical file/package summaries
• Cross-session decision memory
• systemd/launchd user service helper

License

MIT