Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

docs: governance baseline for AAIF project proposal

Rohit Ghumare7ee6c70a73cf
diff --git a/.github/AAIF-PROPOSAL-DRAFT.md b/.github/AAIF-PROPOSAL-DRAFT.md
new file mode 100644
index 00000000..01bb39b9
--- /dev/null
+++ b/.github/AAIF-PROPOSAL-DRAFT.md
@@ -0,0 +1,116 @@
+# AAIF Project Proposal — draft for agentmemory
+
+Paste the fields below into <https://github.com/aaif/project-proposals/issues/new?template=project-proposal.yml> when ready.
+
+---
+
+**Project Name**
+agentmemory
+
+**Project Description**
+agentmemory is a persistent, local-first memory runtime for AI coding agents. It captures session observations via 12 auto-hooks, compresses them into semantic memories, and serves retrieval through a hybrid triple-stream (BM25 + vector + temporal knowledge graph) pipeline — with zero external databases. It ships as three npm packages: `@agentmemory/agentmemory` (the server), `@agentmemory/mcp` (a standalone MCP server), and `@agentmemory/fs-watcher` (a filesystem connector). It has first-party integrations for Claude Code, OpenClaw, Hermes, and Codex CLI, and is MCP-native so any Model Context Protocol client — Cursor, Claude Desktop, Gemini CLI, VS Code, Cline, Windsurf, OpenCode, Goose, Aider — works out of the box. The project was started in January 2026 and is currently at v0.9.0 with 1,786 GitHub stars, 173 forks, and 6 contributors.
+
+**Alignment with AAIF Mission**
+agentmemory advances "the public interest in agentic AI innovation" by removing the single biggest failure mode of today's coding agents: loss of context between sessions. It does so under Apache-2.0, without vendor lock-in, and without requiring developers to stand up Redis, Postgres, Qdrant, or Neo4j. All memory is stored locally on the user's machine by default. The project is a direct, neutral consumer of the AAIF-hosted Model Context Protocol — every agentmemory tool is available through the MCP surface — which is the exact category of foundational interoperability AAIF exists to steward.
+
+**Relation to Existing AAIF Projects**
+- **Model Context Protocol (MCP)** — agentmemory is a first-class MCP server. The `@agentmemory/mcp` package is a standalone stdio MCP server exposing 44 tools; the main package registers the same tools via in-process MCP. Both pass validation against the MCP reference test suite.
+- **goose** — agentmemory works with goose via the same MCP configuration pattern documented for Claude Desktop and Cursor. We plan to ship a goose-specific integration guide in Q3 2026.
+- **AGENTS.md** — agentmemory reads `AGENTS.md` at session start and treats its contents as high-confidence context, surfaced ahead of observation-derived memory in the recall pipeline.
+
+**Example Use Cases and Evidence of Adoption**
+Core use cases:
+1. Cross-session context preservation — "what did I change in the retry logic last Tuesday?" surfaces commit, session, and file-level memories in a single recall call.
+2. Team knowledge sharing — the mesh-sync feature pushes curated memories to peer nodes over authenticated HTTPS, enabling shared memory across a dev team.
+3. Defect debugging — the session replay feature rehydrates a Claude Code JSONL transcript into full observation form, so a maintainer can re-enter the session that produced a bug.
+4. Compliance trails — every structural deletion emits an audit row (scoped for user-initiated actions, batched for automatic sweeps) per the policy in `src/functions/audit.ts`.
+
+Adoption evidence:
+- 1,786 GitHub stars, 173 forks, 6 commit contributors as of April 2026.
+- Three npm packages published with provenance and downloaded regularly (`npm view @agentmemory/agentmemory`).
+- Featured in the Claude Code plugin marketplace as `agentmemory@agentmemory`.
+- The [design doc gist](https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2) that seeded the project has 775 stars and 106 forks.
+- 95.2% retrieval R@5 on the public LongMemEval-S benchmark, independently reproducible via the in-repo harness.
+
+Production deployments in named organizations: we are compiling case studies now and will update this section as deployers opt in to being listed. The current installation base is primarily individual developers; enterprise case studies are a Q3 2026 roadmap item.
+
+**Technical Committee Sponsor (if identified)**
+Not yet identified. We would welcome an introduction.
+
+**GitHub Repository URL**
+<https://github.com/rohitg00/agentmemory>
+
+**License**
+Apache-2.0 (OSI-approved, permissive). <https://github.com/rohitg00/agentmemory/blob/main/LICENSE>
+
+**Governance Model**
+Documented in <https://github.com/rohitg00/agentmemory/blob/main/GOVERNANCE.md>. The model follows the Linux Foundation Minimum Viable Governance pattern, scoped to the project's current single-maintainer reality with a concrete plan (see `ROADMAP.md`) to add at least one additional Maintainer from a different organization during the current growth cycle.
+
+**CI/CD & Release Workflow**
+GitHub Actions:
+- `.github/workflows/ci.yml` — runs TypeScript build + 777-test Vitest suite on every PR against Node 20 and Node 22.
+- `.github/workflows/publish.yml` — triggers on GitHub Releases. Publishes `@agentmemory/agentmemory`, `@agentmemory/mcp`, and `@agentmemory/fs-watcher` to npm with provenance, in order, with registry-propagation wait gates between them. Also exposes `workflow_dispatch` for manual publishes.
+
+Release cadence: minor releases every 2–4 weeks; patch releases as needed. Each release goes through a `release/vX.Y.Z` PR that bumps 8 in-repo version strings in lockstep (see `CONTRIBUTING.md#release-process`), is tagged `vX.Y.Z` on merge, and auto-publishes via the workflow.
+
+**Public-Facing Contribution Process for Specifications**
+<https://github.com/rohitg00/agentmemory/blob/main/CONTRIBUTING.md> documents the full PR flow, DCO sign-off requirement, coding style, subsystem layout, and the process for adding new MCP tools and auto-hooks. Non-code / policy changes follow the process in `GOVERNANCE.md#non-pr-decisions` — a `governance`-labeled issue with a 7-day public comment window.
+
+**Publicly Accessible Issue Tracker**
+<https://github.com/rohitg00/agentmemory/issues> — no gating, standard labels, issue template for bug reports in `.github/ISSUE_TEMPLATE/`.
+
+**External Project Dependencies**
+Runtime:
+- `iii-sdk` (Apache-2.0) — three-primitive engine runtime.
+- `@anthropic-ai/claude-agent-sdk` (MIT) — default LLM provider when a Claude subscription is detected.
+- `@modelcontextprotocol/sdk` (MIT) — MCP server runtime.
+- Optional: `@google/generative-ai` (Apache-2.0), `openai` (Apache-2.0), upstream minimax / openrouter — each behind a provider flag.
+
+Build-time only:
+- `tsdown` (MIT), `vitest` (MIT), `typescript` (Apache-2.0).
+
+Full lockfile at <https://github.com/rohitg00/agentmemory/blob/main/package-lock.json>.
+
+**Maintainers & Contributors**
+Current Maintainers (from `MAINTAINERS.md`):
+- Rohit Ghumare ([@rohitg00](https://github.com/rohitg00)) — Independent — project lead, all subsystems.
+
+Named non-Maintainer contributors with merged PRs:
+- [@Tanmay-008](https://github.com/Tanmay-008) — retention scoring, semantic eviction routing, multimodal image memory.
+- [@JasonLandbridge](https://github.com/JasonLandbridge)
+- [@Getty](https://github.com/Getty)
+- [@eng-pf](https://github.com/eng-pf) — security fixes.
+- [@Garygaoxiang](https://github.com/Garygaoxiang)
+
+Full contributor graph: <https://github.com/rohitg00/agentmemory/graphs/contributors>. We transparently disclose that maintainership is currently single-organization; the Q2–Q3 2026 roadmap commits to changing this.
+
+**Leadership Team & Decision Process**
+See `GOVERNANCE.md#decision-making`. Lazy consensus on PRs, formal votes on governance items (simple majority of Maintainers with a 7-day public comment window during single-maintainer periods).
+
+**Roadmap**
+<https://github.com/rohitg00/agentmemory/blob/main/ROADMAP.md>. 12 months of planned work broken into four quarterly themes: Depth (Q2), Breadth (Q3), Trust (Q4), v1.0 (Q1 2027).
+
+**Security**
+- Security policy at <https://github.com/rohitg00/agentmemory/blob/main/SECURITY.md>.
+- Six CVE-tracked v0.8.2 advisories published through GitHub Security Advisories, drafts archived under `.github/security-advisories/`.
+- OpenSSF Best Practices Silver-or-better badge: not yet enrolled. Enrollment is a Q3 2026 roadmap item.
+
+**Website URL**
+Ships in-repo under [`website/`](https://github.com/rohitg00/agentmemory/tree/main/website) (Next.js 16 App Router, deployable to Vercel with Root Directory = `website/`). Primary documentation remains the repository README.
+
+**Documented Governance Practices (optional)**
+See `GOVERNANCE.md` above.
+
+**Links to Social Media Accounts (optional)**
+- Author X: <https://x.com/ghumare64>
+
+**Details of Existing Financial Sponsorship (optional)**
+None. The project is developed in-kind by the Maintainer.
+
+**Infrastructure Needs or Requests (optional)**
+- Continued GitHub Actions CI minutes (currently within the free tier for public repos).
+- LF-hosted domain delegation if/when we move from `agentmemory.dev` to a foundation-owned hostname.
+- Potential CI time for the LongMemEval-S benchmark harness (Q2 2026 roadmap item) — the harness pulls a ~200 MB dataset and runs under ~15 minutes per release.
+
+**Additional Information**
+Applying for **Growth Stage**. We do not currently meet the Impact Stage criterion of "a diverse group of maintainers, with multiple organizations represented"; the `ROADMAP.md` commits to addressing that during the Growth cycle.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 00000000..d0e57135
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,38 @@
+# Code of Conduct
+
+agentmemory follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+The short version:
+
+- Be kind. Assume good faith.
+- Disagree on the idea, not the person.
+- Harassment — in issues, PRs, discussions, or any other project space — is not tolerated.
+- Unwelcome behavior gets moderated first by reminder, then by time-out, then by removal.
+
+## Enforcement
+
+Reports go to **[email protected]** with subject `agentmemory CoC`. All reports are confidential.
+
+Responses follow the Covenant's enforcement ladder — correction, warning, temporary ban, permanent ban — and are decided by the project Maintainers listed in [MAINTAINERS.md](./MAINTAINERS.md). Where a Maintainer is a party to the report, that Maintainer recuses.
+
+## Scope
+
+This applies to every project space:
+
+- GitHub issues, PRs, discussions, and reviews on this repo.
+- Any official chat channel that gets set up (currently none).
+- Public representation of the project at conferences, meetups, and on social media.
+
+## Full text
+
+Reproduced verbatim from the Contributor Covenant 2.1 for convenience:
+
+> We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+>
+> We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+Full Covenant v2.1 text: <https://www.contributor-covenant.org/version/2/1/code_of_conduct/>
+
+## Attribution
+
+Contributor Covenant is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..a52b2c89
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,115 @@
+# Contributing to agentmemory
+
+Thanks for taking an interest. This file is the short path from "I have an idea" to "it's in main."
+
+## Ground rules
+
+- Apache-2.0 license applies to every contribution.
+- Sign-off is required on every commit (see [DCO](#developer-certificate-of-origin) below).
+- Be civil. [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) applies.
+- No attribution headers ("Generated with Claude Code", "Co-Authored-By: Claude", etc.) in commits or PR descriptions.
+
+## Before you open an issue
+
+Search existing issues first:
+
+- [open issues](https://github.com/rohitg00/agentmemory/issues?q=is%3Aissue+is%3Aopen)
+- [closed issues](https://github.com/rohitg00/agentmemory/issues?q=is%3Aissue+is%3Aclosed)
+
+If it's a bug: provide the repro steps, your Node version, OS, agentmemory version (`npm view @agentmemory/agentmemory version`), and what you expected vs. what you saw.
+
+If it's a feature: describe the user problem before the implementation. "I couldn't X because Y" beats "please add X."
+
+## Before you open a PR
+
+1. Fork the repo and create a branch off `main`:
+ - `feat/<short-name>` for features
+ - `fix/<issue-number>-<short-name>` for bug fixes
+ - `docs/<topic>`, `refactor/<topic>`, `chore/<topic>` for the rest
+2. `npm install` — you need Node >=20.
+3. `npm run build` — TypeScript must compile clean.
+4. `npm test` — 777+ tests must pass. The one integration test under `test/integration.test.ts` needs a live server and is fine to skip locally.
+5. Commit with sign-off. Rebase over tiny fixup commits so the history stays readable.
+
+## Pull request flow
+
+- Keep PRs small and focused. One logical change per PR.
+- Write a clear description: what it does, why, and how to verify.
+- Link the issue the PR resolves (`Fixes #NNN` / `Closes #NNN`).
+- Expect CodeRabbit to review automatically. Address its comments before asking a human.
+- Address review feedback in new commits (do not force-push to the same branch). Maintainers may squash on merge.
+- A maintainer will merge when tests pass, CodeRabbit is green, and any review comments are addressed.
+
+## Developer Certificate of Origin
+
+Every commit must carry a `Signed-off-by` trailer stating you have the right to submit the contribution under Apache-2.0. The full text of the DCO is at <https://developercertificate.org>.
+
+Add it automatically:
+
+```bash
+git commit -s -m "feat: your message"
+```
+
+PRs with commits lacking sign-off will not merge.
+
+## Coding style
+
+- TypeScript strict mode. No `any` unless justified in a comment.
+- Prettier-compatible formatting (editor on save is fine; no repo-wide hook).
+- No code comments that restate what the code does. Only write a comment when the *why* is non-obvious — a hidden constraint, an invariant, a workaround for a specific bug.
+- No dead code, no commented-out imports.
+- Tests live next to the feature in `test/<feature>.test.ts`. Name the test after the behavior, not the implementation.
+
+## Subsystems at a glance
+
+| Directory | What lives here |
+|-|-|
+| `src/triggers/api.ts` | Every HTTP endpoint under `/agentmemory/*`. Adding an MCP tool? Add the REST twin here too. |
+| `src/mcp/` | Standalone MCP server (`@agentmemory/mcp`), tools registry, transport, in-memory KV. |
+| `src/functions/` | Core memory operations — observe, compress, consolidate, retention, forget, graph, smart-search, export-import, governance. |
+| `src/hooks/` | The 12 auto-hooks that capture sessions in agents. |
+| `src/health/` | Liveness + readiness + alert thresholds. |
+| `src/state/` | KV schema, keyed mutex, access log. |
+| `integrations/` | First-party plugins: `hermes/`, `openclaw/`, `filesystem-watcher/`. |
+| `plugin/` | Claude Code plugin (`agentmemory@agentmemory`). |
+| `website/` | Marketing site (Next.js 16). |
+| `test/` | Vitest test suite. |
+
+## Adding an MCP tool
+
+1. Register the function in `src/functions/<area>.ts`.
+2. Register the HTTP trigger in `src/triggers/api.ts` with a matching `api_path`.
+3. Add the tool entry in `src/mcp/tools-registry.ts`.
+4. Implement in `src/mcp/standalone.ts` if the standalone MCP package should also expose it.
+5. Write a test under `test/`.
+6. No CHANGELOG touch in the PR itself — release PRs are the only place CHANGELOG changes.
+
+## Adding an auto-hook
+
+1. Add the new `HookType` string to the union in `src/types.ts`.
+2. Wire the handler in `src/hooks/<hook-name>.ts`.
+3. Add a Vitest case that fires the hook and asserts the observation gets written.
+
+## Release process
+
+Maintainers cut releases. Every bump touches 8 files in lockstep:
+
+1. `package.json`
+2. `package-lock.json` (top + `packages[""].version`)
+3. `plugin/.claude-plugin/plugin.json`
+4. `packages/mcp/package.json` (self + `~x.y.z` pin on the main package)
+5. `src/version.ts` (extend the union, assign)
+6. `src/types.ts` (`ExportData.version` union)
+7. `src/functions/export-import.ts` (`supportedVersions` Set)
+8. `test/export-import.test.ts` (assertion)
+
+Then: CHANGELOG section, PR, merge, tag, GitHub release. The `Publish to npm` workflow picks up the release trigger and publishes `@agentmemory/agentmemory`, `@agentmemory/mcp`, and `@agentmemory/fs-watcher` to npm with provenance.
+
+## Security issues
+
+Do not open a public issue for a security report. See [SECURITY.md](./SECURITY.md).
+
+## Questions
+
+- Implementation questions: open a GitHub Discussion.
+- Governance questions: open an issue labeled `governance`. See [GOVERNANCE.md](./GOVERNANCE.md).
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
new file mode 100644
index 00000000..98527c3d
--- /dev/null
+++ b/GOVERNANCE.md
@@ -0,0 +1,88 @@
+# Governance
+
+This document describes how decisions are made in the agentmemory project.
+
+The model here is a near-copy of the [Linux Foundation Minimum Viable Governance (MVG)](https://github.com/todogroup/ospolog/blob/main/governance/minimum-viable-governance.md) pattern, scoped to the project's current single-maintainer reality with a concrete plan to diversify maintainership over the next two release cycles.
+
+## Mission
+
+Ship a persistent, local-first memory runtime for AI coding agents that:
+
+- Requires zero external databases.
+- Runs under any MCP-compatible client.
+- Stays compatible with the open [Model Context Protocol](https://modelcontextprotocol.io).
+- Keeps every user's data on the user's machine by default.
+
+## Roles
+
+### Users
+
+Anyone who runs agentmemory. No process obligation beyond the license. Feedback via [GitHub issues](https://github.com/rohitg00/agentmemory/issues) and [discussions](https://github.com/rohitg00/agentmemory/discussions) is the input channel.
+
+### Contributors
+
+Anyone who opens an issue, comments on an issue, opens a pull request, or otherwise helps the project. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the how-to.
+
+### Maintainers
+
+A Maintainer has commit access to the repository, responsibility for reviewing PRs, and a vote on project-level decisions. The current list is tracked in [MAINTAINERS.md](./MAINTAINERS.md).
+
+A Maintainer is expected to:
+
+- Respond to PRs they are review-owner for within a reasonable window (goal: 3 working days for first comment).
+- Uphold the [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
+- Avoid merging their own non-trivial PRs without a second reviewer once the maintainer count is greater than one.
+- Disclose conflicts of interest (employer, paid relationships to users).
+
+### Maintainer acceptance process
+
+A Contributor becomes a Maintainer by:
+
+1. Sustained, high-signal contributions over the prior 6 months (multiple merged PRs across more than one subsystem, plus review comments on others' PRs).
+2. A Maintainer nominates the Contributor in a public PR editing `MAINTAINERS.md`.
+3. The PR stays open for 7 calendar days to collect objections.
+4. If no standing objection from an existing Maintainer, the PR merges and the new Maintainer is added.
+
+A Maintainer steps down by opening a PR that moves their entry to the `Emeritus` section. This is always accepted.
+
+## Decision-making
+
+### Default: lazy consensus on PRs
+
+Most decisions happen inside pull requests. A PR merges when any Maintainer approves it and no other Maintainer blocks it. Silence is assent after 72 hours of no objection.
+
+### Non-PR decisions
+
+Anything that is not a normal code change — charter changes, governance edits, maintainer additions/removals, project scope, breaking API changes, relicensing — happens in a GitHub Issue labeled `governance` with a proposal in the first comment.
+
+- Minor scope decisions: rough consensus in the issue thread, captured by a Maintainer in a summary comment.
+- Formal votes: Maintainers react `+1` / `-1` / `0` to the summary comment. Simple majority of Maintainers with a minimum of two distinct voters carries. If only one Maintainer exists, a 7-day public comment window substitutes for a vote.
+
+### Breaking changes
+
+A breaking change to the REST / MCP surface requires:
+
+1. A tracking issue labeled `breaking` opened at least one minor release cycle ahead of the change.
+2. A deprecation path in the codebase (warning log, feature flag, or adapter) for at least one minor release.
+3. The change landing in the CHANGELOG under a clearly marked `Breaking` sub-section.
+
+## Release process
+
+Releases follow [Semantic Versioning](https://semver.org). See [reference_agentmemory_release_checklist](./CONTRIBUTING.md#release-process) in `CONTRIBUTING.md` and the automated `.github/workflows/publish.yml` pipeline for the mechanics.
+
+## Conflicts of interest
+
+Maintainers employed by a company that sells a product competing with agentmemory, or by a company whose business depends on agentmemory's roadmap, should disclose that relationship in `MAINTAINERS.md` next to their name. Nothing prohibits such maintainership; transparency is the requirement.
+
+## Amending this document
+
+This document changes by PR. Edits follow the Non-PR decisions path above: open a `governance` issue, collect feedback, then open the PR citing the issue.
+
+## Related documents
+
+- [LICENSE](./LICENSE) — Apache-2.0
+- [CONTRIBUTING.md](./CONTRIBUTING.md) — how to contribute
+- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) — community behavior
+- [SECURITY.md](./SECURITY.md) — how to report a vulnerability
+- [MAINTAINERS.md](./MAINTAINERS.md) — who has commit access
+- [ROADMAP.md](./ROADMAP.md) — where the project is heading
diff --git a/MAINTAINERS.md b/MAINTAINERS.md
new file mode 100644
index 00000000..182d46af
--- /dev/null
+++ b/MAINTAINERS.md
@@ -0,0 +1,31 @@
+# Maintainers
+
+The authoritative list of people with commit access. See [GOVERNANCE.md](./GOVERNANCE.md) for what a Maintainer is, what they do, and how someone becomes one.
+
+## Active
+
+| Name | GitHub | Affiliation | Area of focus | Since |
+|-|-|-|-|-|
+| Rohit Ghumare | [@rohitg00](https://github.com/rohitg00) | Independent | Project lead, all subsystems | 2026-01 |
+
+## Emeritus
+
+_None yet._
+
+## Maintainer recruitment
+
+agentmemory is actively looking to diversify maintainership. The growth plan in [ROADMAP.md](./ROADMAP.md) commits to adding at least one additional Maintainer from a different organization by the end of the current growth cycle.
+
+If you have a sustained contribution track record and would like to be considered, open an issue tagged `governance`.
+
+## Notable contributors (non-maintainer)
+
+These people have shipped meaningful PRs and are on the short list for future Maintainer review:
+
+- [@Tanmay-008](https://github.com/Tanmay-008) — retention scoring, semantic eviction routing, multimodal image memory (PR #111).
+- [@JasonLandbridge](https://github.com/JasonLandbridge) — ecosystem contributions.
+- [@Getty](https://github.com/Getty) — ecosystem contributions.
+- [@eng-pf](https://github.com/eng-pf) — security fixes.
+- [@Garygaoxiang](https://github.com/Garygaoxiang) — ecosystem contributions.
+
+The complete contributor graph: <https://github.com/rohitg00/agentmemory/graphs/contributors>
diff --git a/ROADMAP.md b/ROADMAP.md
new file mode 100644
index 00000000..66fb5467
--- /dev/null
+++ b/ROADMAP.md
@@ -0,0 +1,92 @@
+# Roadmap
+
+This is agentmemory's public 12-month roadmap. It covers Q2 2026 through Q1 2027. The roadmap is the source of truth for where the project is heading; anything significant that lands in main should trace back to an item here or a ratified issue.
+
+Items shift as evidence changes. Each quarter we publish a short retrospective on what landed, what slipped, and why — attached to the release notes.
+
+## How to read this
+
+- **Shipped** — landed in main and tagged in a release.
+- **Active** — in-flight, has an open PR or issue owner.
+- **Planned** — accepted scope for the quarter, not started.
+- **Candidate** — under consideration, may defer.
+
+Anything not on this list that a contributor wants to pursue is welcome — open an issue labeled `roadmap` and it gets triaged against the quarterly theme.
+
+## Themes
+
+- **Q2 2026 — Depth.** Multimodal memory, more connectors, close out backlog from the v0.9 cycle.
+- **Q3 2026 — Breadth.** Hook parity across more agents, community expansion, OpenSSF best-practices alignment.
+- **Q4 2026 — Trust.** Enterprise features — SSO, audit export, RBAC, long-running deployment story.
+- **Q1 2027 — v1.0.** Stability, LTS branch, semver freeze on the REST + MCP surface.
+
+## Q2 2026 — Depth (April – June)
+
+### Shipped so far in this quarter
+- [x] iii console docs in README with vendored screenshots (#157)
+- [x] Health severity gated on RSS floor (#158 / PR #160)
+- [x] Standalone MCP proxies to the running server (#159 / PR #161)
+- [x] Audit coverage for `mem::forget` + audit policy doc (#125 / PR #162)
+- [x] `@agentmemory/fs-watcher` filesystem connector (#62 / PR #163)
+- [x] Next.js website on Vercel (PR #164)
+- [x] CI publishes all three npm packages on release (PR #166)
+
+### Active
+- [ ] **Multimodal memory** — content-addressed image store, vision-prompt compression, disk quota + refcount on eviction (#64, PR #111)
+- [ ] **Governance baseline** — this file, plus `GOVERNANCE.md`, `CONTRIBUTING.md`, `MAINTAINERS.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`
+
+### Planned
+- [ ] **GitHub connector** (`@agentmemory/github-watcher`) — sync issues, PRs, discussions as observations. Shares the `POST /agentmemory/observe` wire format with the filesystem connector.
+- [ ] **OpenCode hook bus** (#156) — if upstream ships hook events, wire them; otherwise ship a REST-polling adapter.
+- [ ] **Session replay UI** in the real-time viewer — scrub the timeline, inspect per-observation payloads.
+- [ ] **Benchmark harness in CI** — keep the 95.2% R@5 number honest across releases by re-running LongMemEval-S on every minor tag.
+
+## Q3 2026 — Breadth (July – September)
+
+### Planned
+- [ ] **Additional maintainer onboarding** — at least one Maintainer from a different organization added via the process in `GOVERNANCE.md`. This is a prerequisite for advancing past the foundation's Growth Stage.
+- [ ] **Slack / Discord connector** — third source in the connector family.
+- [ ] **OpenSSF Scorecard** — enroll, reach a Silver-equivalent score. Badged in the README.
+- [ ] **Hermes integration hardening** — reach parity with the OpenClaw plugin surface (session lifecycle + tool-use hooks).
+- [ ] **Knowledge graph query language** — small DSL on top of `/agentmemory/graph` for multi-hop questions.
+- [ ] **First conference talk** — submit to KubeCon / LlamaCon / similar.
+
+### Candidate
+- Cross-agent shared memory namespace. Currently each agent installs its own instance. This would let a Claude Code session and a Cursor session recall each other's observations via a shared mesh node.
+
+## Q4 2026 — Trust (October – December)
+
+### Planned
+- [ ] **SSO gateway** — accept OIDC in front of the REST surface for team deployments.
+- [ ] **Audit log export** — streamable tail to S3 / Loki / stdout for compliance pipelines.
+- [ ] **RBAC on memory scope** — `project:read`, `project:write`, `governance:delete` role set.
+- [ ] **Long-running deployment guide** — first-class Docker, systemd unit, and launchd plist.
+- [ ] **Performance SLO** — publish p50/p95 recall latency targets, enforce via the benchmark harness.
+- [ ] **Security audit** — external review of the REST surface + mesh-sync path. Fund through LF if foundation acceptance lands before end of quarter.
+
+### Candidate
+- Agent-to-agent memory handoff protocol — standardize what one agent can inherit from another's memory, complementing MCP.
+
+## Q1 2027 — v1.0 (January – March)
+
+### Planned
+- [ ] **REST + MCP surface freeze.** Any break requires a major-version tag per `GOVERNANCE.md`.
+- [ ] **LTS branch `v1.x`** — 12-month security-fix commitment.
+- [ ] **v1.0 release** — full documentation pass, all roadmap items from prior quarters either shipped or formally deferred.
+- [ ] **Foundation membership** — Growth → Impact stage application if adoption + maintainer diversity metrics justify.
+
+### Candidate
+- Hosted reference instance for the community to benchmark against.
+- Reference implementation in a second language (Rust or Go) for the MCP server — would expand the set of runtimes that can host agentmemory.
+
+## Out of scope
+
+For transparency, these are deliberately *not* on the roadmap:
+
+- A cloud-hosted agentmemory SaaS.
+- Billing, subscription tiers, commercial licensing beyond Apache-2.0.
+- Agent frameworks themselves — agentmemory is a dependency, not a replacement for the agent runtime.
+
+## Feedback
+
+Anything on this list you disagree with, or think should move up / down — open an issue tagged `roadmap`. Quarterly themes are revisited with every quarterly retrospective.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 00000000..6d4bd602
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,59 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+**Do not open a public GitHub issue for a suspected vulnerability.**
+
+Use one of:
+
+- **GitHub Security Advisories** — private report form at <https://github.com/rohitg00/agentmemory/security/advisories/new>. This is the preferred channel. GitHub routes the report to the Maintainers and assigns a GHSA identifier. You stay in a private thread with us until the fix ships.
+- **Email** — `[email protected]` with subject `agentmemory security`. Please do not encrypt the mail unless you and we have already exchanged keys.
+
+Include, at minimum:
+
+- agentmemory version (`npm view @agentmemory/agentmemory version` against your install).
+- The affected surface — REST endpoint, MCP tool, hook, CLI flag, or filesystem layout.
+- A minimal reproduction — prefer one curl invocation or one MCP tool call plus the environment state required.
+- Impact, in your own words.
+
+## What we do with it
+
+1. **Acknowledge** within 72 hours (target: 24).
+2. **Triage** — confirm reproduction, assign a severity using CVSS 3.1, and give you a rough timeline.
+3. **Fix** in a private branch. Draft a GitHub Security Advisory with the patched version, CWE, CVSS vector, affected versions, and attribution to you (unless you prefer anonymity).
+4. **Coordinate disclosure** — we agree a disclosure date with you. Default window is 30 days from acknowledgment for straightforward vulnerabilities, up to 90 days for ones that need a deep refactor.
+5. **Publish** — release the patched version on npm, publish the advisory, update `CHANGELOG.md` under a `### Security` section for the release, notify downstream scanners.
+
+## Supported versions
+
+| Version | Security fixes? |
+|-|-|
+| Latest minor (currently `0.9.x`) | Yes |
+| Previous minor (currently `0.8.x`) | Critical / High severity only, for 90 days after a new minor releases |
+| Older | No |
+
+At v1.0 this policy switches to a stated LTS window per the roadmap.
+
+## Scope
+
+In scope:
+
+- The `@agentmemory/agentmemory` server (REST + MCP surface, hook handlers, state store).
+- The `@agentmemory/mcp` standalone MCP server.
+- The `@agentmemory/fs-watcher` connector.
+- First-party integrations under `integrations/` (`hermes/`, `openclaw/`, `filesystem-watcher/`).
+- The Claude Code plugin under `plugin/`.
+
+Out of scope:
+
+- Third-party MCP clients consuming agentmemory — report to those projects.
+- `iii-sdk` upstream — report to the iii project.
+- The marketing site under `website/` unless the issue affects user security (XSS against visitors, credential leak in build output).
+
+## Past advisories
+
+See the [`.github/security-advisories/`](./.github/security-advisories) directory for advisory drafts. Published advisories (with assigned GHSA IDs) live at <https://github.com/rohitg00/agentmemory/security/advisories>.
+
+## Safe harbor
+
+Good-faith research, reported privately, does not get legal heat from the project. Research targeting third-party deployments of agentmemory is not covered — that's between you and the deployer.