{"id":"9176f7ed-1be7-40f6-9538-fb1f577d89d2","slug":"chrisstarr7-dev-memory","kind":"skill","name":"dev-memory","summary":"Private local development memory for AI coding agents. Independent project stores, corrections, and task continuity.","owner":"chrisstarr7","repoUrl":"https://github.com/chrisstarr7/dev-memory","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-10-11T02:29:45.000Z","addedAt":"2026-10-21T11:44:06.310Z","logoUrl":"https://avatars.githubusercontent.com/u/123819749?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge","databases","productivity"],"tags":["developer-tools","local-memory","python","sqlite"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T20:38:17.575Z","sample":false,"url":"https://conduits.dev/tools/chrisstarr7-dev-memory","language":"Python","transports":["stdio"],"install":{"npm":"dev-memory"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<h1 align=\"center\">dev-memory</h1>\n\n<p align=\"center\"><strong>Local memory for your development habits and project rules.</strong></p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/chrisstarr7/dev-memory/actions/workflows/check.yml\"><img src=\"https://github.com/chrisstarr7/dev-memory/actions/workflows/check.yml/badge.svg\" alt=\"Program checks\" /></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-08C\" alt=\"MIT License\" /></a>\n  <img src=\"https://img.shields.io/badge/Python-3.10%2B-3776AB\" alt=\"Python 3.10 or newer\" />\n  <img src=\"https://img.shields.io/badge/storage-local%20SQLite-4493F8\" alt=\"Local SQLite storage\" />\n</p>\n\n<p align=\"center\"><strong>English</strong> · <a href=\"docs/readme/README.zh-CN.md\">简体中文</a> · <a href=\"docs/readme/README.ja.md\">日本語</a> · <a href=\"docs/readme/README.ko.md\">한국어</a></p>\n\nDev Memory is a Skill and local Python program for AI-assisted development. It helps your assistant recall relevant habits and project rules, then save durable knowledge backed by requirements or evidence. The assistant judges meaning; the program validates and stores records in SQLite.\n\n## Install\n\nRun this from the root of a development project:\n\n```sh\nnpx -y --prefer-online chrisstarr7/dev-memory codex\n```\n\nFor another AI host, replace `codex` with its parameter:\n\n| Host | Parameter | Project guidance |\n| --- | --- | --- |\n| Codex | `codex` | `AGENTS.md` or an existing nonempty `AGENTS.override.md` |\n| Claude Code | `claude` | `CLAUDE.local.md` |\n| Cursor | `cursor` | `.cursor/rules/dev-memory.mdc` |\n| Gemini CLI | `gemini` | `GEMINI.md` |\n| GitHub Copilot | `copilot` | `.github/copilot-instructions.md` |\n| OpenCode | `opencode` | `AGENTS.md` |\n| DeepSeek Harness | `deepseek` | `AGENTS.md` |\n\nInstallation needs Node.js 22+ with npm/npx, Git, and Python 3.10+ with sqlite3. The memory runtime uses only the Python standard library. Choose the host running the assistant: DeepSeek through OpenCode uses `opencode`.\n\nCodex setup enables global habits for your user and project memory for the current project. In an uninitialized project, its user guidance recalls global habits only. Run the install command again in each project that needs its own memory. Other hosts currently use project guidance only. After installation or upgrade, start a new AI session in the project. You can then work normally without invoking the Skill or saying “remember this.” New stores start empty; existing records are retained.\n\nSee [installation and removal](docs/installation.md) for alternate paths, permissions, and host details.\n\n## What it remembers\n\nDev Memory has **two persistent scopes**:\n\n| Scope | What belongs there | Example |\n| --- | --- | --- |\n| Global | De-identified development habits useful across projects | Check for a suitable existing implementation before adding one |\n| Current project | Durable rules, contracts, decisions, and evidenced facts | API requirements, security boundaries, coding conventions |\n\nTemporary requests, work in progress, and unconfirmed guesses stay in the current conversation. Dev Memory does not save conversation transcripts or task checkpoints. A new chat may need to inspect the code to recover progress. Never save credentials in either scope.\n\nProject knowledge can include acceptance rules, compatibility, deployment constraints, migrations, and verified incident lessons. Save a code observation only if it is durable, non-obvious, and likely to change future work; it describes what exists, not what the user wants. The assistant keeps the original scope and checks for equivalent records before writing. A review-only task can still reveal a durable new rule, even when the code already complies.\n\nFor global habits, an explicit ongoing cross-project instruction can become an active rule immediately. A reusable requirement, choice, or correction without that explicit scope is first saved as an **inactive candidate**. It becomes an active soft preference only after evidence from two independent tasks. AI summaries and repeated recall do not count as new evidence.\n\nNew project stores use `full-project` mode, which allows eligible project knowledge to be saved automatically. The optional `developer-first` mode blocks new project records. Upgrades preserve existing modes and pause, disable, and read-only controls; switching an older project to `full-project` is explicit.\n\n## How it works\n\nFor an initialized project, this [Mermaid flowchart](https://mermaid.js.org/syntax/flowchart.html) shows how recall guides the task and how new information is assessed during the work:\n\n```mermaid\nflowchart TD\n    S([Task starts or topic changes]) --> R[Recall global and current project memory]\n    R --> A[Turn applicable active memory into task decisions and checks]\n    A --> W[Do the task; note new information as it appears]\n    W --> E[Assess future use, evidence, durability, scope, controls and existing records]\n    E --> G{Eligible change to save?}\n    G -->|No| F([Deliver result])\n    G -->|Yes| P[Add or update in the owning store; check the receipt]\n    P --> F\n```\n\nThe capture question applies to requirements, choices, conventions, decisions, verified facts, methods, and corrections—not just mistakes. Assess new information when it appears and at turn end, including review-only work. Save an important correction before the edit it affects; save other eligible increments before delivery.\n\nCurrent instructions take priority over memory. The AI turns applicable active records, including their conditions and exceptions, into task decisions and checks; inactive candidates are not instructions. Recheck old observations and test results against the workspace. Recall supplies context to the AI; a returned record alone does not prove the AI followed it.\n\nGlobal and project writes have separate receipts; report a failed or partial write accurately. No eligible increment means no empty write.\n\n## Organization\n\nChanged active rules and inactive non-hypothesis candidates enter a queue in their own store. Five pending records, a pending body of at least 1,200 characters, or an unreviewed change waiting the default seven-day interval can make one related group due for review.\n\n```mermaid\nflowchart TD\n    S([An eligible rule or candidate changes]) --> Q[Queue its revision in the owning store]\n    Q --> D{Review due?}\n    D -->|No| L([Leave queued for later])\n    D -->|Yes| M[Return due metadata]\n    M --> B{Quiet task boundary?}\n    B -->|No| L\n    B -->|Yes| R[Read one related pack]\n    R --> C{Safe action justified after full review?}\n    C -->|No| L\n    C -->|Yes| A[Merge, compact, retag or mark reviewed]\n    A --> F[Revision-checked apply and inspect receipt]\n    F --> E([Finish; remaining work waits])\n```\n\nOne turn handles at most one related pack per store, with a limit of 8 records and 12,000 characters. Unread, oversized, or uncertain records stay explicit and queued; a character limit never permits dropping a condition. Organization preserves evidence and inactive candidate status. There is no daemon, continuous conversation listener, or required extra model call. The [protocol](skills/dev-memory/references/protocol.md) specifies operations, controls, and revision checks.\n\n## Storage and privacy\n\n| Location | Contents |\n| --- | --- |\n| `~/.dev-memory/global/` | Global SQLite store, configuration, optional views and backups |\n| `<project-root>/.dev-memory/` | This project's SQLite store and activation binding |\n\nOne project lookup opens the global store and that project’s store; it does not search other projects. Separate clones and worktrees have separate project stores by default. SQLite is authoritative; optional Markdown views can be rebuilt. Session and turn IDs support retries, opt-outs, and recall caching. They are operational metadata, not a third memory scope.\n\nThe core has no telemetry or automatic memory upload. Text recalled into a hosted AI is still subject to that host’s data policy. Global records and their evidence must exclude project names, business details, code, paths, customer data, raw dialogue, logs, and secrets. Backups contain private data too.\n\nOlder databases may contain task/checkpoint rows. This version does not create, recall, maintain, or export them. It retains those rows for explicit audit or deletion: use `list --scope project --status all`, then the `forget preview` / `forget apply` workflow. Historical files under `reports/` may describe the former behavior.\n\n## Recall statistics\n\nWhen a memory's full details are returned, its UTC monthly counter increments in that store. Candidate indexes, cached results, read-only calls and capture-paused stores do not increment. This measures delivery to the assistant, not confirmed use. Run `<python> <skill>/scripts/dev_memory.py --global-root <global-root> recall-stats --scope both --month 2026-10 --project-root .` for a month; use `--from-month 2026-07 --to-month 2026-09` for a quarter. Reports do not store prompts or conversation text.\n\n## Local memory dashboard\n\nThe dashboard runs locally on demand. For a Codex installation on macOS or Linux:\n\n```sh\npython3 ~/.agents/skills/dev-memory/scripts/dev_memory.py dashboard serve\n```\n\nUse the installed Skill path for another host or location. The command opens the browser; press `Ctrl+C` in the terminal to stop the server.\n\n| Task | How |\n| --- | --- |\n| View memory | Select **Global** or a registered project; open a record to see its full text, evidence, and revisions. |\n| Find records | Filter by status or search titles and bodies. A project list has pages; cross-project search shows at most 50 matches. |\n| Preview recall | Enter task terms on a store page. The preview is read-only and does not increment recall counts. |\n| Add an existing project | Use **Project management → Add**, or run `dashboard add --project-root /absolute/project/path` with the same CLI. New project setups register automatically. |\n| Manage records | Use the record page to revise or archive eligible records, or preview the impact before permanent forgetting. Back up a store from **Project management**. |\n\n`dashboard list` shows registered paths and IDs; `dashboard remove --namespace-id ID` removes only the catalog entry. A disabled or excluded store shows no memory content. Monthly counts mean full details were returned to the AI, not that the AI followed them; earlier periods cannot be reconstructed. The page binds only to `127.0.0.1`, uses a temporary access token, and does not upload memory or combine project databases.\n\n## Control it in plain language\n\n- “For this project, document changes to API request and response fields.”\n- “Across all projects, check existing implementations before adding code.”\n- “Pause global learning but keep reading existing habits.”\n- “Do not save any memory from this turn.”\n- “Show the relevant memories.”\n- “Preview records to delete before forgetting them.”\n\nThe current request always takes priority. To investigate missing capture or recall, ask the assistant to run the **installed** CLI’s `doctor` once. Check activation, capture mode, store access, candidate versus active status, and actual write receipts. An installation receipt or a model’s “remembered” message alone does not prove a record was saved or used.\n\n## Update\n\nFor an existing managed installation, run the update command from the project and start a new AI session:\n\n```sh\nnpx -y --prefer-online chrisstarr7/dev-memory update codex\n```\n\nReplace `codex` with your host parameter. Update preserves existing stores, controls, and unrelated instructions. It does not initialize an unbound project. Updating a source checkout alone does not update the installed Skill.\n\n## More detail\n\n- [Architecture](docs/architecture.md): components and storage boundaries.\n- [Protocol](skills/dev-memory/references/protocol.md): CLI operations, evidence, maintenance, and limits.\n- [Installation and removal](docs/installation.md): hosts, paths, and troubleshooting.\n- [Verification evidence](reports/verification.md): completed checks and known gaps.\n- [Security](SECURITY.md) · [Contributing](CONTRIBUTING.md) · [MIT license](LICENSE).\n\nReport sanitized issues at [GitHub Issues](https://github.com/chrisstarr7/dev-memory/issues). Do not attach private databases, credentials, or raw conversations.\n"}