Metadata-Version: 2.5
Name: lybrary
Version: 0.3.1
Summary: Local codebase memory MCP server for Codex, Claude Code, and coding agents
Project-URL: Homepage, https://vibhu-dixit.github.io/lybrary/
Project-URL: Documentation, https://vibhu-dixit.github.io/lybrary/
Project-URL: Repository, https://github.com/vibhu-dixit/lybrary
Project-URL: Issues, https://github.com/vibhu-dixit/lybrary/issues
Project-URL: Changelog, https://github.com/vibhu-dixit/lybrary/blob/main/CHANGELOG.md
Author: lybrary contributors
License-Expression: MIT
Keywords: Claude Code,Codex,MCP server,code search,codebase memory,coding agents
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: Programming Language :: Python :: 3.13
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 — local codebase memory for coding agents

Lybrary indexes a repository by code structure and gives Codex, Claude Code, and other MCP clients a searchable map of its functions, classes, and files. It runs locally, watches for changes, and lets an agent find relevant source lines before opening whole files.

<!-- mcp-name: io.github.vibhu-dixit/lybrary -->

[PyPI](https://pypi.org/project/lybrary/) · [Documentation](https://vibhu-dixit.github.io/lybrary/) · [Source](https://github.com/vibhu-dixit/lybrary) · [Issues](https://github.com/vibhu-dixit/lybrary/issues)

## Start in any repository

Install once, then run `lybrary start` in each folder you want indexed:

```bash
pip install lybrary
cd /path/to/your/repo
lybrary start
lybrary status
```

`start` creates `.lybrary/` if needed, builds the index, and runs a file-watching daemon in the background. It keeps running after the terminal closes. Run `lybrary stop` in that repository to stop it. The first indexing run may download the local embedding model; later runs use the cache.

Each repository has its own index and `.lybrary/config.toml`. The index stays on your machine; no API key or hosted database is required.

## Connect an agent

Register the MCP server once on your machine. Start your agent in an indexed repository, then ask it to call `memory_status` to confirm the root and chunk count.

### Codex

```bash
codex mcp add lybrary -- lybrary mcp
codex mcp list
```

Add this to that repository's `AGENTS.md` if you want Codex to use the memory consistently:

```markdown
When .lybrary/index.db exists, use Lybrary memory_query before broad code searches or reading multiple files. Inspect the returned source paths and lines before editing. If the index is absent or the tool fails, use normal search.
```

### Claude Code

```bash
claude mcp add --scope user --transport stdio lybrary -- lybrary mcp
claude mcp list
```

In Claude Code, `/mcp` shows connection status. Put the same instruction in the repository's `CLAUDE.md`. Registration makes the tool available; the instruction helps the agent choose it when useful.

For another stdio MCP client, configure command `lybrary` with argument `mcp`. See the [setup guides](https://vibhu-dixit.github.io/lybrary/).

## What the agent gets

`memory_query` checks exact symbols and an SQLite FTS5 index first. Strong lexical matches avoid loading the embedding model; semantic search remains a fallback when wording does not match the code. Its default response gives ranked paths, symbols, line ranges, and compact numbered excerpts. If a trace crosses a named call missing from the first result, query that symbol once. Set `include_content=true` when a full chunk is needed.

`memory_status` reports the active repository and index health. `memory_update` triggers incremental, full, or path-scoped re-indexing.

This can avoid repeated broad searches and large file reads, especially when the agent needs to locate a feature across sessions. Actual token use depends on the task, the agent's tool choices, and how much source it still needs to inspect. The [benchmark guide](https://vibhu-dixit.github.io/lybrary/token-usage.html) explains how to compare complete runs rather than infer savings from the size of one response.

## Make it fit your repo

Edit `.lybrary/config.toml` to choose the embedding model and device, chunk sizes, indexed languages, excluded paths, and file-watcher debounce. Add Git-style ignore patterns to `.lybrary/ignore`. Re-run `lybrary index --full` after changing settings that affect stored chunks or embeddings.

Supported parsers: Python, JavaScript, TypeScript, TSX, Go, Rust, Java, C, and C++. The indexer uses tree-sitter boundaries and refreshes changed files while the daemon is running.

## CLI

| Command | Purpose |
| --- | --- |
| `lybrary start` | Initialize, index, and watch the current repository |
| `lybrary stop` | Stop its background daemon |
| `lybrary status` | Show daemon and index status |
| `lybrary query "authentication flow"` | Search from the terminal |
| `lybrary index --full` | Rebuild the index |
| `lybrary logs` | Show daemon logs |
| `lybrary mcp` | Run the stdio MCP server |

If an agent starts above the indexed repository, pass that repository's absolute path as `repo_root` to the MCP tool, or start the agent inside it.

## Measure the effect

From a source checkout, compare the same read-only question with and without Lybrary:

```bash
python benchmark.py /path/to/indexed/repo "Trace how interview invitations are sent"
```

The script records both answers, tool calls, and total, cached, and uncached input tokens under `.lybrary/benchmarks/`. Check answer correctness first; one question does not establish typical savings.

## Contribute

Issues and pull requests are welcome. For a local checkout:

```bash
pip install -e ".[dev]"
pytest
```

Lybrary is MIT licensed. See the [changelog](CHANGELOG.md) for releases.
