Mnemon Laravel Package

Getting Started

Mnemon is not a composer require library — it is a self-hosted Laravel application (Passport for OAuth, Filament v5 for admin) that you run as a service and talk to over MCP. Budget accordingly: you are deploying infrastructure, not adding a trait.

1. Look at the demo first. https://trymnemon.com runs a read-only instance with a sample brain. Click through /wiki and /palace before you install anything — it is the fastest way to understand wings → rooms → drawers (verbatim, append-only) versus wiki pages (compiled, typed markdown, staleness-tracked).
2. Bring the stack up locally. The documented path is the Docker quickstart: docker compose up -d. It binds to loopback by default, so nothing is exposed until you deliberately change it. Set DOMAIN only when you want the optional automatic HTTPS.
3. Stay keyless for the first run. The quickstart ships MNEMON_EMBEDDING_DRIVER=none, so no OpenAI account and no spend. Search degrades to full-text plus recency — good enough to validate the workflow, not good enough to judge retrieval quality (see Gotchas).
4. Read in this order: README Quickstart → docs/USERGUIDE.md → the Limitations section. The limitations list is unusually honest and several items (wiki scoping by page name, single-tenant admin) affect design decisions you make on day one.
5. First real use case: install the Claude Code plugin via curl -fsSL https://<your-instance>/install | bash, then run /mnemon:doctor. That command checks tools, config, token, reachability and performs a real tool call, telling you what to fix. It is the correct first debugging step and saves an hour of guessing.

If you install from source instead of Docker, treat it as a normal Laravel app: composer install, .env, artisan migrate, Passport keys, queue worker. Verify against the repo — the release notes only commit to the Docker path.

Implementation Patterns

Model it as a service with one OAuth client per integration. Register a distinct OAuth client for each environment and each caller (local dev, staging, prod worker, your laptop's Claude Code). Wing restrictions are stored per OAuth client at the consent screen, so separate clients are what make least-privilege real. Scopes must include mcp:use.

Wing-per-bounded-context. Create a wing per application, team, or domain (billing, onboarding, infra-runbooks). Write raw facts and transcripts into drawers; let wiki pages be compiled from them. This maps cleanly onto a Laravel codebase where each domain module or team owns its wing and its own restricted token.

Drive it from Laravel jobs, not from controllers. A listener or scheduled job that calls POST /mcp for recall or session_digest keeps request latency out of your app and lets you retry. Use the HTTP client with an explicit timeout — the transport is request/response only, so a slow compile is a slow HTTP call.

Use the three hook points differently. Session-start injection (recent palace state) and per-prompt injection (relevant context) are for interactive developer tooling; the end-of-session digest is the one you want to mirror in your own pipeline if you use agents outside Claude Code. The hooks are a reference implementation of the pattern, not a general-purpose SDK.

Schedule wiki maintenance yourself. mnemon:auto-compile-stale only reports. A nightly job should read its report and issue compile calls for the stale pages you care about, then a lint pass. Treat the wiki as a build artifact with a cron, not as something that heals itself.

Compile a nightly digest into a durable page. The combination people actually want: end-of-day job runs session_digest for each active session, then compiles/refreshes a "what happened this week" page per wing. The knowledge graph and revision history tools make that page diffable over time.

Ops through Filament, humans through /wiki and /palace. /admin is for you (users, config, browsing). /wiki and /palace are for the team to read what the agents learned. Put the admin panel behind the same proxy auth as everything else.

Integrate via MCP, not by reaching into the database. The 14 tools are the contract: drawers, wiki pages, lint, compile, knowledge graph, revision history, recall, session_digest. Anything you do with raw SQL against the palace tables is unsupported and will not respect wing restrictions.

Local testing: keep MNEMON_EMBEDDING_DRIVER=none in CI so tests cost nothing and need no account; the suite runs on SQLite (697 passed, 9 skipped) and CI mirrors it on PostgreSQL 17. If you fork, that suite is your regression net — run it on Postgres before trusting search behaviour.

Gotchas and Tips

• This is an application, not a package. No composer require, no service provider to register in your app. Upgrades are pull-image-and-migrate. v1.0.0 is the first release, so there is no battle-tested upgrade path yet — pin the image tag and read the changelog before every bump.
• A client registered without wing restrictions is effectively full access. Restrictions are set at the consent screen, so a hastily approved client has the run of the palace. Audit your OAuth clients the same way you audit personal access tokens. Tokens live 1 hour and refresh tokens 90 days — build refresh into anything long-running or you will get mysterious 401s in a cron job.
• Wiki pages are scoped by name, not by source. A generically named page compiled from a restricted wing is governed by its name alone, and index pages are invisible to restricted tokens. Enforce a naming convention (billing/…, infra/…) in whatever compiles pages, or your isolation model quietly becomes advisory.
• Hidden reads exactly like missing. That is deliberate, and it means "why can't this token see the drawer?" is answered by checking the client's wing restriction and the resource name — never by checking whether the row exists. Do not build UX that distinguishes the two cases; you cannot.
• Restricted tokens have sharp edges. wiki_lint auto-fix requires an unrestricted token, and a restricted context_set still rebuilds the wiki-wide wiki:index and wiki:log. If you need cross-wing index pages accurate, run those operations from a dedicated unrestricted service token and keep it off developer machines.
• session_digest replay keys on session id, not device. Running the same session digest from two machines can collide or double-write. Dedupe client-side, or keep digesting to a single designated runner.
• Keyless mode is a real quality drop, and SQLite has no semantic search at all. Benchmark delta for the retrieval layer: hit_rate@1 0.742 → 0.886, recall@5 0.832 → 0.952, MRR 0.817 → 0.924, QA accuracy 0.557 → 0.627. If retrieval quality matters, move to Postgres with pgvector and switch to the openai or ollama driver. Do not evaluate the product on a SQLite dev box.
• Single-tenant by design: any registered user is an admin in Filament. Never expose /admin to the internet without proxy-level auth. This alone rules the v1.0.0 instance out for multi-user deployments.
• No streaming on the MCP transport. Long compiles and digests are one blocking request. Raise PHP, queue, and reverse-proxy timeouts together, and prefer triggering heavy work from artisan rather than from a request path.
• TRUSTED_PROXIES is untested end to end. Behind nginx/Traefik, verify X-Forwarded-* handling, HTTPS scheme detection, and — the classic breakage — OAuth redirect URIs. Test the full device-grant flow through the proxy, not just curl /mcp.
• The install script turns on plugin auto-update for the Mnemon marketplace (off by default for third-party marketplaces). Convenient on a laptop; disable it or vendor the plugin if you need pinned behaviour.
• /mnemon:doctor first, always. It exercises tools, config, token, reachability, and a real tool call. Only after it is green should you start reading logs.
• Benchmarks cover the palace only, and the QA leg is graded by the same model family that answers. Treat the numbers as directional evidence that embeddings help, not as an absolute quality claim about the wiki.