@vaur94/agz-memory

AGZ Memory

English | Türkçe

AGZ Memory gives OpenCode V2 a durable, project-scoped linked memory. It ships as two independently usable packages that advance at the same version:

• @vaur94/agz-memory: a nine-tool MCP server, TypeScript core, and recovery CLI backed by SQLite.
• @vaur94/agz-memory-plugin: an optional OpenCode V2 adapter for bounded retrieval and deliberately staged automatic capture.

The MCP server is ready for normal use. The plugin starts inert: no project is created, no session is captured, and no context is injected until an explicit binding and rollout mode are configured.

Why AGZ Memory

• Every read and mutation is scoped by an immutable project UUID or unique project name.
• Notes can be pinned, linked, superseded, revised, searched, and inspected without mixing projects.
• SQLite schema v10 is the canonical source of truth; optional semantic indexes are replaceable derivatives.
• Destructive project deletion requires the immutable ID, exact current name, and a fixed confirmation phrase.
• Backup manifests include row counts, SQLite integrity results, size, and SHA-256 before restore is allowed.
• Automatic capture is redacted, bounded, idempotent, and disabled by default.

Compatibility

Component	Supported version
Core and MCP	0.4.1
OpenCode plugin	0.4.1
OpenCode V2	0.0.0-beta-18743
@opencode-ai/plugin	0.0.0-beta-18743
Bun	>=1.3.14
SQLite schema	10

The MCP server is not tied to an OpenCode beta. The optional plugin disables itself unless the running OpenCode version exactly matches the supported beta.

Install The MCP Server

Run the server directly:

bunx @vaur94/agz-memory@0.4.1

Or register it in OpenCode V2 under mcp.servers:

{
  "mcp": {
    "servers": {
      "agz-memory": {
        "type": "local",
        "command": ["bunx", "@vaur94/agz-memory@0.4.1"],
        "environment": {
          "OPENCODE_MEMORY_DATABASE_PATH": "{env:OPENCODE_MEMORY_DATABASE_PATH}"
        },
        "codemode": false
      }
    }
  }
}

The default database is ~/.local/share/opencode-memory/memory.sqlite. Set OPENCODE_MEMORY_DATABASE_PATH before OpenCode starts to use another path. The database file is created with user-only permissions.

Use The Nine Tools

OpenCode exposes the tools with the configured server prefix, for example agz-memory_project_list. The MCP protocol names remain:

Tool	Purpose
project_list	List project identities and note counts.
project_create	Create an empty project with a unique name.
project_update	Rename a project without changing its UUID.
project_delete	Permanently delete one confirmed project and all owned data.
memory_recall	Search one project with one or up to ten queries.
memory_update	Create, patch, or explicitly delete notes in one project.
memory_pin	Prioritize or unprioritize one active note.
memory_link	Add typed links between notes in the same project.
memory_read	Read full notes, pin state, project identity, and graph neighbors.

Recommended sequence:

• Call project_list and reuse an existing project when it represents the same durable workspace.
• Call project_create only when no matching project exists.
• Keep the returned projectID; names can change, UUIDs cannot.
• Call memory_recall before relying on historical decisions.
• Store only durable, verified facts, decisions, procedures, preferences, research, context, or tasks. Do not store transcripts, secrets, or guesses.

All multi-item mutations are ordered and non-atomic. Inspect every result: earlier items remain applied when a later item fails.

Add The Optional Plugin

Keep the MCP server configured, then add the exact plugin package with inert options:

{
  "plugins": [
    {
      "package": "@vaur94/agz-memory-plugin@0.4.1",
      "options": {
        "mode": "off",
        "autoCreateProjects": false,
        "bindings": [],
        "capture": {
          "enabled": false,
          "allowedKinds": ["preference", "decision"],
          "minConfidence": 0.95
        },
        "retrieval": {
          "semanticBackend": "none",
          "timeoutMs": 300,
          "maxCards": 8,
          "maxCharacters": 4800
        }
      }
    }
  ]
}

The plugin opens the same database path as the MCP server. It rejects unknown configuration fields, automatic project creation, unsupported semantic backends, oversized limits, and conflicting bindings.

Bind Projects Explicitly

The plugin does nothing without exactly one matching binding. Each binding maps an OpenCode project/workspace/location to an existing AGZ Memory project:

{
  "memoryProjectID": "11111111-1111-4111-8111-111111111111",
  "opencodeProjectID": "your-opencode-project-id",
  "canonicalDirectory": "/absolute/canonical/project/path",
  "workspaceID": ""
}

memoryProjectID must come from project_list. The directory is resolved with the filesystem and compared with the active OpenCode location. Only a hash of that canonical path is persisted. A mismatched location or duplicate mapping disables the plugin rather than selecting a project heuristically.

Roll Out Safely

Modes are intentionally one-way stages:

Mode	Capture	Retrieval	Injection	Note writes
off	No	No	No	No
shadow-capture	Redacted audit only	No	No	No
shadow-retrieval	Optional redacted audit	Measured only	No	No
inject	Optional redacted audit	Lexical and graph	Bounded, untrusted	No
auto-write	Policy-gated	Lexical and graph	Bounded, untrusted	High-confidence candidates only

Advance one stage at a time and inspect agz-memory-admin capture status, database growth, retrieval latency, and false matches before proceeding. To disable retrieval, injection, and every capture channel for one complete turn, include [memory:off] in that prompt. Reconciliation reconstructs this boundary from session history after a restart. Returning to off is always safe and does not delete stored data.

Semantic retrieval remains hard-disabled. semanticBackend must be none until a vendor passes project isolation, delete, purge, rebuild, leakage, quality, and latency gates.

Operate And Recover

The admin CLI reads the same OPENCODE_MEMORY_DATABASE_PATH:

bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup
bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin upgrade --to 10
bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin capture status
bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin outbox status

Upgrades take an exclusive migration lock and create a verified backup before changing the database. A failed migration attempts an automatic verified restore. Restore and backup deletion use dry-run output plus explicit confirmation values; never guess them.

Use the backup and restore runbook for a full rehearsal. Final 0.4.1 backup manifests use agz-memory-backup/1; prerelease manifests must be handled by the prerelease that created them.

Security Model

• Retrieved notes are wrapped in <agz-memory-context trust="untrusted"> and escaped before injection. Stored text never becomes system policy.
• Capture projects only terminal user/assistant text and terminal tool status; reasoning, tool input, and tool output payloads are excluded.
• Credential patterns are redacted before persistence and again before note materialization. Private-key material is quarantined without a payload.
• Capture events are idempotent by stable source identity and retained with bounded payload lifetimes.
• Project ownership is enforced in every note and edge query. Cross-project links and backend hits are rejected.
• The SQLite database is canonical. Derived-index outbox rows contain identity and hashes, not note payloads.

Report vulnerabilities privately as described in SECURITY.md.

Develop And Verify

bun install --frozen-lockfile
bun run release:verify
bun test
bun run check
bun run build
bun run benchmark 10000 100
npm pack --dry-run --json

release:verify rejects package-version drift, mismatched bilingual sections, stale beta pins, and any tracked reintroduction of the retired project name. The test suite covers project isolation, destructive confirmation, migration, backup/restore, capture safety, revisions, provenance, FTS, retrieval, outbox, and the exact nine-tool MCP surface.

Project Resources

• Architecture
• Changelog
• Backup and restore runbook
• Contributing
• Security policy
• GitHub repository
• npm core package
• npm plugin package

License

MIT