{"id":47688914,"url":"https://github.com/ironadamant/stele-context","last_synced_at":"2026-04-15T01:00:25.059Z","repository":{"id":343924531,"uuid":"1179646902","full_name":"IronAdamant/stele-context","owner":"IronAdamant","description":"Local context cache for LLM agents. 100% offline, zero dependencies.","archived":false,"fork":false,"pushed_at":"2026-04-10T04:27:31.000Z","size":974,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T06:28:43.169Z","etag":null,"topics":["code-indexing","developer-tools","llm","mcp","offline-first","python","semantic-search","sqlite","vector-search"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IronAdamant.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-12T08:33:12.000Z","updated_at":"2026-04-10T04:27:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/IronAdamant/stele-context","commit_stats":null,"previous_names":["ironadamant/chunkforge","ironadamant/stele"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/IronAdamant/stele-context","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IronAdamant%2Fstele-context","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IronAdamant%2Fstele-context/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IronAdamant%2Fstele-context/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IronAdamant%2Fstele-context/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IronAdamant","download_url":"https://codeload.github.com/IronAdamant/stele-context/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IronAdamant%2Fstele-context/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31821685,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-indexing","developer-tools","llm","mcp","offline-first","python","semantic-search","sqlite","vector-search"],"created_at":"2026-04-02T15:13:26.409Z","updated_at":"2026-04-15T01:00:24.960Z","avatar_url":"https://github.com/IronAdamant.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stele Context\n\n**Persistent memory for AI coding agents. An MCP server that helps Claude Code, Claude Desktop, Cursor, and other AI tools remember your codebase between conversations.**\n\n[![PyPI](https://img.shields.io/pypi/v/stele-context.svg)](https://pypi.org/project/stele-context/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-green.svg)](https://github.com/IronAdamant/stele-context)\n[![Tests](https://github.com/IronAdamant/stele-context/actions/workflows/test.yml/badge.svg)](https://github.com/IronAdamant/stele-context/actions)\n\n## The Problem\n\nEvery time you start a new conversation with Claude Code, Cursor, or any AI coding assistant, it has to read your files from scratch. For a medium-sized project, that's thousands of tokens spent re-reading code that hasn't changed since last time. Your AI agent has no memory of what it already knows about your project.\n\n## What Stele Context Does\n\nStele Context gives your AI coding agent persistent memory across conversations. It:\n\n1. **Indexes your project files** once — code, docs, configs, even images and PDFs\n2. **Detects what changed** since last time — only changed files get re-read\n3. **Searches your code** by meaning or keywords, not just filenames\n4. **Tracks how your code connects** — knows which files import from which, so it can tell your agent \"if you change this file, these other files might break\"\n\nEverything runs **locally on your machine**. No internet, no API calls, no cloud. Just Python and SQLite.\n\n![Semantic search demo](docs/semantic-search-demo.png)\n\n## Quick Start\n\n### Install\n\n```bash\npip install stele-context\n```\n\n### Index your project\n\n```bash\nstele-context index src/ docs/ README.md\n```\n\nThis reads your files, breaks them into meaningful chunks, and stores them locally in a `.stele-context/` folder in your project.\n\n### Search your code\n\n```bash\nstele-context search \"how does authentication work\"\nstele-context search \"database connection\" --top-k 10\n```\n\n### Connect it to Claude Code or Claude Desktop\n\nStele Context works as an [MCP server](https://modelcontextprotocol.io/) — a plugin that gives your AI agent extra tools.\n\n```bash\npip install stele-context[mcp]\n```\n\n**Claude Code** — add to `~/.claude/settings.json`:\n```json\n{\n  \"mcpServers\": {\n    \"stele-context\": {\n      \"command\": \"stele-context\",\n      \"args\": [\"serve-mcp\"]\n    }\n  }\n}\n```\n\n**Claude Desktop** — add to `~/.config/Claude/claude_desktop_config.json` (Linux/Mac) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n```json\n{\n  \"mcpServers\": {\n    \"stele-context\": {\n      \"command\": \"stele-context\",\n      \"args\": [\"serve-mcp\"]\n    }\n  }\n}\n```\n\n\u003e **Tip:** If you installed in a virtualenv, use the full path: run `which stele-context` to find it.\n\nOnce connected, your agent gets **~32 tools** for searching, indexing, and navigating your code — it'll use them automatically when they're helpful. (Set `STELE_MCP_MODE=lite` for ~15 essential tools, or `STELE_MCP_MODE=full` for the complete surface.)\n\n## Who Is This For?\n\n- You use **Claude Code**, **Claude Desktop**, **Cursor**, or another AI coding tool\n- You're tired of your agent re-reading the same files at the start of every conversation\n- You want your AI to **remember your codebase** and know how your code connects\n- You want a **code search tool** that understands your project, not just filenames\n- You want something that runs **100% offline** with **no API keys** and **no cloud**\n\nIf you've ever wished your AI coding assistant had a persistent memory for your project, that's what this does.\n\n## What Can It Do?\n\n### For everyday use\n\n| What you want | How Stele helps |\n|---------------|-----------------|\n| \"Don't re-read files that haven't changed\" | `get_context` returns cached content for unchanged files, only re-reads modified ones |\n| \"Ask a broad question about my code\"\" | `query` combines semantic search, symbol graph, and text grep into one deduplicated result list |\n| \"What files would break if I change this?\" | `impact_radius` follows the dependency chain to find affected files; `significance_threshold` filters out noise from common symbols like `push`/`addEdge`. Also works with `symbol=` for dynamic/runtime hooks and `direction=` for outgoing or bidirectional traversal |\n| \"Which files are tightly coupled?\" | `coupling` shows shared symbols with a `semantic_score` that discounts generic boilerplate. `mode=co_consumers` catches files imported together by the same consumers |\n| \"Search my code by what it does, not just keywords\" | `search` combines meaning-based and keyword matching |\n| \"Find every line matching a pattern\" | `agent_grep` does text/regex search with token-budgeted results |\n| \"Run several operations in one round-trip\" | `batch` executes multiple tool calls under a single write lock |\n\n### For power users\n\n- **Multi-agent safe** — Multiple AI agents can share the same index without stepping on each other (document locking, version tracking, conflict detection)\n- **Works with git worktrees** — Each worktree gets its own index, with shared coordination across all of them\n- **Session management** — Save and restore agent state between conversations (rollback, pruning)\n- **Supports many file types** — Code (12 languages), text, Markdown, images, PDFs, audio, video (some need optional packages)\n\n## How Much Does It Save?\n\n| What changed | Tokens without Stele | Tokens with Stele | Savings |\n|--------------|---------------------|-------------------|---------|\n| Nothing (same code) | 10,000 | 0 | 100% |\n| A typo fix | 10,000 | ~100 | 99% |\n| Edited a few functions | 10,000 | ~1,000 | 90% |\n| Rewrote the whole file | 10,000 | 10,000 | 0% |\n\nThe less your code changes between conversations, the more tokens you save.\n\n## Python API\n\nYou can also use Stele Context directly in Python scripts:\n\n```python\nfrom stele_context import Stele\n\nengine = Stele()\n\n# Index your project\nresult = engine.index_documents([\"src/\", \"README.md\"])\nprint(f\"Indexed {result['total_chunks']} chunks\")\n\n# Search by meaning or keywords\nresults = engine.search(\"authentication logic\", top_k=5)\nfor r in results:\n    print(f\"{r['document_path']}: {r['content'][:100]}...\")\n\n# Check what changed since last time\nchanges = engine.detect_changes_and_update()\nprint(f\"{len(changes['modified'])} files changed, {len(changes['new'])} new files\")\n\n# Find where a function/class is used\nrefs = engine.find_references(\"MyClassName\")\nprint(f\"Verdict: {refs['verdict']}\")  # referenced, unreferenced, external, or not_found\n\n# What breaks if I change this file?\nimpact = engine.impact_radius(document_path=\"src/main.py\")\nprint(f\"{impact['affected_files']} files could be affected\")\n\n# Analyze impact of a dynamic/runtime symbol\nimpact = engine.impact_radius(symbol=\"onRecipeCreate\")\nprint(f\"{impact['affected_files']} files could be affected\")\n```\n\n## Configuration\n\nCreate a `.stele-context.toml` in your project root to customize behavior:\n\n```toml\n[stele-context]\nchunk_size = 512                # How big each chunk is (in tokens)\nskip_dirs = [\".git\", \"node_modules\", \"dist\", \"vendor\"]\n```\n\nAll settings are optional — defaults work well for most projects.\n\n\u003cdetails\u003e\n\u003csummary\u003eAll configuration options\u003c/summary\u003e\n\n```toml\n[stele-context]\nstorage_dir = \".stele-context\"   # Where to store the index\nchunk_size = 256                 # Target tokens per chunk\nmax_chunk_size = 4096            # Maximum tokens per chunk\nmerge_threshold = 0.7            # When to merge similar adjacent chunks\nchange_threshold = 0.85          # When to consider a chunk \"unchanged\"\nsearch_alpha = 0.42              # Balance between meaning-based and keyword search\nskip_dirs = [\".git\", \"node_modules\", \"__pycache__\"]\n```\n\nYou can also set `STELE_CONTEXT_STORAGE_DIR` as an environment variable, or pass options directly in Python:\n\n```python\nengine = Stele(chunk_size=512, skip_dirs=[\".git\", \"node_modules\", \"dist\"])\n```\n\nPriority: Python arguments \u003e `.stele-context.toml` \u003e environment variables \u003e defaults.\n\n\u003c/details\u003e\n\n## Optional Extras\n\nThe core package has **zero dependencies** — it runs on Python's standard library alone. Optional packages add support for more file types and better performance:\n\n```bash\npip install stele-context[tree-sitter]   # Better code understanding (9 languages)\npip install stele-context[image,pdf]     # Image and PDF support\npip install stele-context[performance]   # Faster search with numpy\npip install stele-context[all]           # Everything\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eFull extras list\u003c/summary\u003e\n\n| Extra | What it adds |\n|-------|-------------|\n| `performance` | Faster math for search (numpy, msgspec) |\n| `tree-sitter` | Better code parsing for JS/TS, Java, C/C++, Go, Rust, Ruby, PHP |\n| `image` | Index and search images (Pillow) |\n| `pdf` | Extract text from PDFs (pymupdf) |\n| `audio` | Index audio files (librosa) |\n| `video` | Index video keyframes (opencv) |\n| `mcp` | MCP server for Claude Desktop/Code |\n| `all` | All of the above |\n\n\u003c/details\u003e\n\n## Supported File Types\n\n**Built-in (no extra packages needed):**\n`.py`, `.js`, `.ts`, `.jsx`, `.tsx`, `.java`, `.cpp`, `.c`, `.h`, `.go`, `.rs`, `.rb`, `.php`, `.swift`, `.sh`, `.sql`, `.html`, `.css`, `.json`, `.yaml`, `.toml`, `.md`, `.txt`, `.rst`, `.csv`, `.log`\n\n**With optional packages:**\nImages (`.png`, `.jpg`, `.gif`, etc.), PDFs, audio (`.mp3`, `.wav`, etc.), video (`.mp4`, `.avi`, etc.)\n\n## Troubleshooting\n\n**`ImportError: No module named 'stele_context'`**\nMake sure it's installed: `pip install stele-context`. If using a virtualenv, activate it first.\n\n**MCP server not connecting**\nUse the full path to the binary. Run `which stele-context` and put that path in your config.\n\n**`PermissionError` when indexing**\nAnother agent might be holding a lock. Run `stele-context` with the `reap_expired_locks` tool to clean up.\n\n## FAQ\n\n**How do I make Claude Code remember my project between conversations?**\nInstall Stele Context and add it as an MCP server (see Quick Start above). Once connected, Claude Code can index your project and recall file contents, symbol locations, and code structure across conversations without re-reading everything.\n\n**Does this work with Cursor / other AI coding tools?**\nYes. Stele Context runs as an MCP server, which is a standard protocol. Any AI tool that supports MCP can use it. It also has an HTTP REST API and a Python library for direct integration.\n\n**Does it need an internet connection or API keys?**\nNo. Everything runs locally on your machine. No API calls, no cloud, no model downloads, no telemetry. Zero dependencies — just Python's standard library.\n\n**Is my code safe?**\nYes. Your code never leaves your machine. No data is sent anywhere. Zero third-party dependencies means no supply chain risk. ~13,000 lines of Python you can read and audit yourself.\n\n**Can multiple AI agents use it at the same time?**\nYes. Built-in document locking and version tracking prevent agents from stepping on each other.\n\n**Where is the data stored?**\nIn a `.stele-context/` folder in your project root. It's just a SQLite database and some index files. Each git worktree gets its own.\n\n**How is this different from just using CLAUDE.md or project memory?**\nCLAUDE.md gives your agent instructions. Stele Context gives it a searchable index of your entire codebase — every function, every import, every file relationship. It knows what changed since last time and can answer \"where is this function used?\" or \"what breaks if I change this file?\" without reading everything again.\n\n## Learn More\n\n- [AGENTS.md](AGENTS.md) — How AI agents should use Stele Context\n- [Design philosophy](docs/philosophy.md) — Why it's built this way\n- [Agent workflow](docs/agent-workflow.md) — Step-by-step agent integration guide\n- [CHANGELOG](CHANGELOG.md) — What changed in each version\n- [Technical architecture](docs/architecture.md) — Deep dive into internals\n\n## Development\n\n```bash\npip install -e \".[dev]\"\npytest                              # 880+ tests\npytest --cov=stele_context           # With coverage\nmypy stele_context/                 # Type checking\nruff check stele_context/           # Linting\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fironadamant%2Fstele-context","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fironadamant%2Fstele-context","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fironadamant%2Fstele-context/lists"}