Mnemon Laravel Package

Product Decisions This Supports

• Build vs. buy for the agent memory layer. Mnemon is a Laravel application you deploy, not a Composer library you require. It bundles the four components every "our agents should remember things" ticket eventually becomes: a verbatim store (palace: wings → rooms → drawers), hybrid retrieval (pgvector + Postgres full-text + recency boost), a compiled human-readable layer (wiki), and an MCP server with OAuth on top. Adopting it replaces a multi-month infrastructure build with an integration task.
• Whether MCP becomes a first-class product surface. 14 tools over Streamable HTTP at POST /mcp, plus a Claude Code plugin with three hooks (session-start injection, per-prompt context, end-of-session digest). This is a working reference implementation for what "MCP-native" looks like in practice — useful when scoping your own roadmap.
• Retrieval quality as a roadmap gate. The LongMemEval-S run (500 questions) is the decision-grade artifact here: keyless (full-text + recency) vs. embedded gives hit_rate@1 0.742 → 0.886, recall@5 0.832 → 0.952, MRR 0.817 → 0.924, QA accuracy 0.557 → 0.627. Read: keyless is fine for demos and cost-free first-run; embedding-enabled Postgres is the baseline for anything a user will judge on answer quality. That's a concrete infra commitment, not a nice-to-have.
• Data-isolation and consent decisions. OAuth 2.1 via Passport with Dynamic Client Registration and device grant, mcp:use scope, and wing restrictions set at the consent screen and stored per OAuth client. Restricted tokens cannot read, search, count, or write another wing's content; hidden items read identically to missing ones. This is a stronger privacy posture than most agent-memory tools ship with, and it directly informs whether you can let third-party MCP clients touch tenant data.
• Multi-tenancy scoping. Single-tenant by design — the admin panel treats any registered user as an admin. That is a hard architectural boundary for a PM: this is an internal/personal deployment, not a SaaS backend, without meaningful work.
• Roadmap backlog, pre-written. The Known Limitations section is a usable prioritization input: wiki pages scoped by name rather than source (leaks across wings for generically named pages), index pages invisible to restricted tokens, lint auto-fix requires an unrestricted token, restricted context_set still rebuilds wiki-wide index/log pages, session_digest replays keyed by session not device, wiki does not self-maintain (auto-compile-stale only reports), no streaming transport, 1h access / 90d refresh tokens.
• Ops and distribution posture. Docker Compose quickstart bound to loopback by default, optional HTTPS via DOMAIN, TRUSTED_PROXIES for reverse proxies (explicitly not tested end to end), and plugin auto-update enabled by the install script (off by default for third-party marketplaces). Each is a decision about how much you operate vs. hand to users.
• Evidence quality signal for a v1.0.0. 697 passed / 9 skipped on SQLite with CI running the same suite against PostgreSQL 17 — plus a published benchmark with a methodology-and-caveats doc. For a "working personal tool," that's unusually honest instrumentation, and it makes the eval defensible in a review.

When to Consider This Package

Consider it when:

• You are building agent-facing products (IDE copilots, chat assistants, internal agent tooling) and the recurring ask is "why doesn't it remember what we told it last week?"
• Your stack is already Laravel/PHP with PostgreSQL — the marginal operating cost is low, and pgvector is the only new dependency that matters.
• You need self-hosted, data-resident memory. The loopback-by-default Docker quickstart and ollama embedding driver mean you can run the whole thing with no external account and no egress for embeddings.
• You want both faithful recall and a curated human-readable layer. The palace/wiki split — append-only verbatim source of truth, typed markdown pages compiled from it with staleness tracking — maps cleanly onto "audit trail plus something a human will actually read."
• You are piloting MCP and want a reference server that already does DCR, device grant, scoped tokens, and a /mnemon:doctor diagnostic that tells a user what to fix instead of making them file a ticket.
• Single-tenant or per-team instance is an acceptable deployment model.

Look elsewhere when:

• You need multi-tenant isolation with per-user admin boundaries. Any registered user being an admin disqualifies this as a shared SaaS substrate as shipped.
• You are on MySQL/SQLite in production. SQLite falls back to full-text + recency, and per the benchmark that is a measurable quality drop; semantic search requires Postgres with pgvector.
• Streaming responses are a product requirement — MCP transport is request/response only.
• You need derived-artifact scoping to be airtight. Wiki pages are scoped by page name, not by their sources; a generically named page compiled from a restricted wing is not reliably walled off. If a compliance reviewer will ask "can a restricted token infer the existence of content it can't read?", the answer is mostly no, with named exceptions — and index pages are invisible to restricted tokens entirely.
• You require vendor support, SLAs, or a maintained release cadence. The author states plainly this is "a working personal tool, not a finished product," and the wiki does not maintain itself.
• Your team has no appetite for operating a Laravel app (queue workers, Passport keys, Postgres, reverse proxy config that is admitted to be untested end to end).

How to Pitch It (Stakeholders)

To executives: We have a recurring, expensive ask across our agent products — persistent memory. Mnemon is a deployable implementation of that entire layer: verbatim storage, hybrid retrieval, a compiled wiki for humans, and a standards-based (MCP) interface that Claude, Cursor, and ChatGPT can already talk to. It ships with a real benchmark rather than a claim: enabling embeddings moves retrieval hit-rate@1 from 0.742 to 0.886 and answer accuracy from 0.557 to 0.627 on a 500-question public eval. It runs keyless and offline for a zero-cost trial, there's a read-only demo with sample data, and the test suite is 697 passing with Postgres 17 in CI. The ask is a time-boxed pilot, not a platform commitment.

To engineering: Adopt as an application, not a dependency — this is a Laravel app you deploy and own. You get Laravel Passport doing OAuth 2.1 with Dynamic Client Registration and device grant, a mcp:use scope, wing-level restrictions persisted per OAuth client, 14 MCP tools over Streamable HTTP, Filament v5 for admin, and a Compose stack that binds to loopback by default. A Claude Code plugin wires session-start injection, per-prompt context, and end-of-session digesting through three hooks, with a /mnemon:doctor command that diagnoses tools, config, token, reachability, and a live tool call. Real constraints to plan around: Postgres + pgvector is required for semantic search, the system is single-tenant with no admin/user separation, tokens are 1h access / 90d refresh, there is no streaming transport, and wiki pages are scoped by name rather than by source — so treat wiki-derived sharing as a design topic, not a solved one.

To security and legal: Self-hosted, loopback-bound by default, optional automatic HTTPS via DOMAIN, and an embedding path (ollama) that keeps everything on-premises. Access is scope-limited and wing-restricted at the consent screen, and a hidden drawer or page is indistinguishable from a missing one. The documented exceptions are narrow but real: name-addressed wiki scoping, wiki_lint auto-fix needing an unrestricted token, and context_set rebuilding wiki-wide index/log pages. We should pilot with a non-sensitive corpus first and let those specific behaviors be validated before anything regulated touches it.

Recommended motion: Two-week pilot, one team, one instance, non-critical knowledge base, embeddings enabled (not keyless), and a scorecard built on our corpus against the published keyless/embedded baseline. Go/no-go on: retrieval quality on our queries, operational burden of running the stack, and whether the wiki scoping behavior is acceptable for our sharing model.