Metadata-Version: 2.4
Name: lybrary
Version: 0.1.0
Summary: Living structure-aware code memory for AI coding agents
Author: lybrary contributors
License-Expression: MIT
Keywords: agent,ast,code,indexing,mcp,memory,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastembed<2.0.0,>=0.4.0
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: numpy<3.0.0,>=1.26.0
Requires-Dist: pathspec<1.0.0,>=0.12.0
Requires-Dist: pydantic-settings<3.0.0,>=2.2.0
Requires-Dist: pydantic<3.0.0,>=2.6.0
Requires-Dist: rich<14.0.0,>=13.7.0
Requires-Dist: tomli-w<2.0.0,>=1.0.0
Requires-Dist: tree-sitter-c<1.0.0,>=0.21.0
Requires-Dist: tree-sitter-cpp<1.0.0,>=0.22.0
Requires-Dist: tree-sitter-go<1.0.0,>=0.21.0
Requires-Dist: tree-sitter-java<1.0.0,>=0.21.0
Requires-Dist: tree-sitter-javascript<1.0.0,>=0.21.0
Requires-Dist: tree-sitter-python<1.0.0,>=0.21.0
Requires-Dist: tree-sitter-rust<1.0.0,>=0.21.0
Requires-Dist: tree-sitter-typescript<1.0.0,>=0.21.0
Requires-Dist: tree-sitter<0.26.0,>=0.24.0
Requires-Dist: typer[all]<1.0.0,>=0.12.0
Requires-Dist: watchdog<6.0.0,>=4.0.0
Requires-Dist: xxhash<4.0.0,>=3.4.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio<1.0.0,>=0.23.0; extra == 'dev'
Requires-Dist: pytest<9.0.0,>=8.0.0; extra == 'dev'
Requires-Dist: ruff<1.0.0,>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
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):

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

The agent then has three tools available:

| Tool | What it does |
|---|---|
| `memory_query` | Semantic search — returns ranked code chunks with full source, file path, and line numbers |
| `memory_status` | Reports daemon state, chunk count, and tracked files |
| `memory_update` | Triggers incremental or full re-index, optionally scoped to specific files |

**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

| Command            | Description                                      |
|--------------------|--------------------------------------------------|
| `lybrary init`     | Create `.lybrary/` and default config            |
| `lybrary start`    | Index (if needed) + start persistent daemon      |
| `lybrary stop`     | Stop the daemon                                  |
| `lybrary status`   | Show running state, chunk count, tracked files   |
| `lybrary index`    | Force (re)index                                  |
| `lybrary query`    | Semantic search over the memory                  |
| `lybrary logs`     | View / follow daemon log                         |
| `lybrary mcp`      | Start MCP server (stdio transport)               |

## 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

- [x] AST chunker (multi-language, cAST-style)
- [x] Incremental indexing via content hashes
- [x] Background daemon + file watcher (Windows + Unix)
- [x] CLI (`init/start/stop/status/index/query/logs/mcp`)
- [x] 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
