{"id":45697946,"url":"https://github.com/danwt/coil","last_synced_at":"2026-02-24T21:09:01.548Z","repository":{"id":339222789,"uuid":"1160987989","full_name":"danwt/coil","owner":"danwt","description":"Structured memory for AI coding agents. Typed schemas, structured queries, utility scoring — an MCP server that makes agents remember what actually matters.","archived":false,"fork":false,"pushed_at":"2026-02-18T19:17:31.000Z","size":51,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-18T19:52:01.539Z","etag":null,"topics":["ai-agents","bun","claude-code","developer-tools","llm-tools","mcp","mcp-server","memory","sqlite","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/danwt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-18T15:54:05.000Z","updated_at":"2026-02-18T19:17:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/danwt/coil","commit_stats":null,"previous_names":["danwt/coil"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/danwt/coil","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danwt%2Fcoil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danwt%2Fcoil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danwt%2Fcoil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danwt%2Fcoil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danwt","download_url":"https://codeload.github.com/danwt/coil/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danwt%2Fcoil/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29800990,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-24T21:02:39.706Z","status":"ssl_error","status_checked_at":"2026-02-24T21:02:21.834Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["ai-agents","bun","claude-code","developer-tools","llm-tools","mcp","mcp-server","memory","sqlite","typescript"],"created_at":"2026-02-24T21:09:00.719Z","updated_at":"2026-02-24T21:09:01.537Z","avatar_url":"https://github.com/danwt.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Coil\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Bun](https://img.shields.io/badge/Bun-runtime-f9f1e1?logo=bun\u0026logoColor=black)](https://bun.sh/)\n[![MCP](https://img.shields.io/badge/MCP-compatible-8B5CF6)](https://modelcontextprotocol.io/)\n[![SQLite](https://img.shields.io/badge/SQLite-local--first-003B57?logo=sqlite\u0026logoColor=white)](https://www.sqlite.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\nStructured memory for AI coding agents. Typed schemas, structured queries, utility scoring, lifecycle hooks.\n\n## The problem\n\nAI coding agents lose everything between sessions. You debug a tricky JWT expiry issue on Monday, and on Wednesday the agent re-debugs the same thing from scratch. You decide on Supabase RLS for auth, and next session it asks \"what auth system are you using?\"\n\nThe existing solutions don't work well:\n\n**Static instruction files** (CLAUDE.md, .clinerules) require you to manually maintain them. You have to remember to remember. They don't evolve, don't capture errors, and don't know which information actually helped.\n\n**Memory MCP servers** (rlm-claude, Mem0, OMEGA, mcp-memory-service) store flat text blobs and retrieve by semantic similarity. This has three fundamental problems:\n\n1. **False-positive retrieval.** \"Use Supabase RLS for row-level auth\" and \"Supabase RLS is broken for multi-tenant\" are semantically similar but functionally opposite. Semantic search returns both when you only want one.\n2. **No quality signal.** A memory retrieved 100 times but never useful ranks the same as one retrieved 3 times and used every time. Everything is weighted equally, so noise accumulates.\n3. **Context separation fails.** Memories from project A leak into project B because the only filter is semantic distance.\n\n## Why Coil works\n\nCoil takes a different approach: **typed schemas + structured SQL queries + usage-based scoring**.\n\n**Typed schemas prevent noise.** Five memory types (`decision`, `pattern`, `error`, `preference`, `context`) with no catch-all. If something doesn't fit these five, it's probably not worth storing. The type system acts as a quality gate at write time.\n\n**Structured queries prevent false positives.** Instead of \"find things semantically similar to auth,\" the agent asks: \"give me all `error` memories tagged `supabase` with utility above 0.7 in project `grupeta`.\" This is a database query, not a similarity search. The filtering happens server-side in SQLite, not in the token window.\n\n**Utility scoring surfaces what actually helps.** Each memory tracks `used_after_retrieval / retrievals` with time decay. A memory that gets retrieved and explicitly marked useful rises toward 1.0. A memory that gets retrieved without positive feedback sinks toward 0.1. Over time, proven knowledge floats up and noise sinks. No ML, no training loop — just counting.\n\n**Project scoping eliminates cross-contamination.** Every memory is tagged with its project (auto-detected from git remote). Queries filter by project by default. Cross-project queries (`project: \"*\"`) are opt-in, not the default.\n\n**Lifecycle hooks automate capture.** You don't have to remember to remember. Claude Code's `SessionStart` hook injects project context automatically. The `PreCompact` hook extracts knowledge before the context window is compacted. The agent calls `coil_feedback` during work, and utility scores update accordingly.\n\nThe result: an agent that starts every session with your past decisions loaded, avoids re-debugging known errors, and improves retrieval quality over time — without manual maintenance.\n\n## Install\n\nRequires [Bun](https://bun.sh/).\n\n### Claude Code (full integration)\n\n```bash\ngit clone https://github.com/danwt/coil.git\ncd coil\n./install.sh\n```\n\nThis registers the MCP server, adds the SessionStart hook, and installs the `/coil` skill. Restart Claude Code to activate.\n\n### As MCP server only (any agent)\n\nIf you only want the MCP tools without Claude Code hooks:\n\n```bash\ngit clone https://github.com/danwt/coil.git\ncd coil\nbun install\n```\n\nThen add to your MCP config (`.mcp.json`, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"coil\": {\n      \"type\": \"stdio\",\n      \"command\": \"bun\",\n      \"args\": [\"run\", \"/absolute/path/to/coil/src/index.ts\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\nCompatible with any MCP client (Claude Code, OpenCode, Cline, Continue, Goose).\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `coil_store` | Store a typed memory. Auto-detects project from git. |\n| `coil_query` | Structured query with typed filters (kind, project, tags, utility, dates). |\n| `coil_feedback` | Report whether a retrieved memory was useful. Updates utility. |\n| `coil_relate` | Create bidirectional link between two memories. |\n| `coil_status` | Overview: counts by kind, project breakdown, top utility. |\n| `coil_context` | Compiled project context. Designed for session start injection. |\n| `coil_forget` | Hard delete a memory. |\n| `coil_search` | Full-text search (FTS5) with optional kind and utility filters. |\n| `coil_export` | Export all memories as JSON. |\n| `coil_import` | Import memories from JSON file. |\n\n## Query examples\n\n```json\n{\n  \"filter\": {\n    \"kind\": [\"error\", \"pattern\"],\n    \"tags\": { \"any\": [\"supabase\", \"auth\"] },\n    \"utility\": { \"gte\": 0.7 },\n    \"project\": \"grupeta\"\n  },\n  \"sort\": \"utility_desc\",\n  \"limit\": 5\n}\n```\n\nCross-project high-utility decisions:\n\n```json\n{\n  \"filter\": {\n    \"kind\": [\"decision\"],\n    \"utility\": { \"gte\": 0.6 },\n    \"project\": \"*\"\n  },\n  \"sort\": \"utility_desc\"\n}\n```\n\n## Storage\n\nSQLite at `~/.coil/coil.db` (override with `COIL_DB_PATH` or `COIL_DB_DIR`). Single file, zero infrastructure, sub-millisecond queries. Data never leaves your machine.\n\n## Debugging and introspection\n\n**From Claude Code:**\n\n- `/coil status` — memory counts by kind, per-project breakdown, top utility items\n- `/coil search \u003cquery\u003e` — full-text search across all memories\n- Ask Claude to run `coil_query` with filters (e.g. all errors for a project, everything above 0.7 utility)\n- Ask Claude to run `coil_export` for a full JSON dump\n\n**From the terminal:**\n\n```bash\n# List all memories sorted by utility\nsqlite3 ~/.coil/coil.db \\\n  \"SELECT id, kind, project, substr(content,1,80), printf('%.2f',utility) FROM memories ORDER BY utility DESC\"\n\n# Count by project and kind\nsqlite3 ~/.coil/coil.db \\\n  \"SELECT project, kind, COUNT(*) FROM memories GROUP BY project, kind\"\n\n# See what SessionStart would inject for the current directory\nbun run /path/to/coil/hooks/context.ts\n\n# Check DB exists and size\nls -lh ~/.coil/coil.db\n```\n\nThe DB is created on the first `coil_store` call. Utility scores start at 0.5 — memories that get retrieved and marked useful via `coil_feedback` climb toward 1.0, unused ones decay toward 0.1.\n\n## Development\n\n```bash\nbun test          # run tests\nbun run check     # typecheck\nbun run dev       # start server with watch mode\n```\n\n## Architecture\n\nSee [ADR-001](docs/adr/001-architecture.md) for core decisions.\n\n```\ninstall.sh        # One-command Claude Code setup\nsrc/\n├── index.ts      # MCP server entry point (10 tools)\n├── store.ts      # SQLite storage layer\n├── schema.ts     # Memory types, Zod schemas, query types\n└── project.ts    # Git-based project auto-detection\nhooks/\n├── context.ts        # Direct SQLite context reader (used by session-start)\n└── session-start.sh\nplugin/\n├── .mcp.json         # MCP server config (template)\n├── hooks.json        # Hook config (template)\n└── skills/coil/SKILL.md\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanwt%2Fcoil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanwt%2Fcoil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanwt%2Fcoil/lists"}