Zigwiz

Shared knowledge. Lasting context.

Zigwiz is a shared agent-memory service with Agent Skills over MCP or an approved restricted CLI/HTTP transport, human review, embedded durable workers, and editable Git Markdown / Confluence views. v0.6 makes the same memory workflow available without MCP.

| Profile | Deployment | Canonical storage | Search | Background jobs | |---|---|---|---|---| | Personal / local | Native Node process or one Docker container | SQLite file | FTS5 | Same SQLite database | | Shared / team | One application container + Postgres | Postgres | Full-text search | pg-boss in the same Postgres instance |

No Redis, separate worker, external scheduler, vector server, or model server is required. Storage selection does not change the MCP tools, scopes, review rules, or view adapters.

Every memory is shared within the instance. user:alice organizes applicability; it is not a private collection. All valid reader credentials can read all scopes. Authentication and write/approval controls remain enabled. Personal mode means a separately operated instance, not a new private-memory flag.

This is an initial implementation, not a production-certified release. See verification, local storage operations, and remaining work.

Install from npm

Use a current patched Node 24 release; the minimum supported runtime is Node 22.16. Install Git when using Git views.

npm install --global zigwiz
zigwiz start
zigwiz attach --clients codex,cursor
zigwiz skills install

zigwiz start initializes ~/.zigwiz on first use without replacing existing files, then runs the service. zigwiz serve is an alias. Client attachment is explicit. zigwiz install is for linking a source checkout onto your PATH; npm installs already provide the zigwiz command.

Run from source

npm ci --ignore-scripts
npm run build
npm run dev

From a source checkout, npm run install:cli links the zigwiz command onto your PATH.

The local home layout:

~/.zigwiz/
├── zigwiz.db          # Memory, revisions, FTS5, approvals, jobs and sync state
├── config.json       # SQLite selection and optional external views
└── .env              # Generated admin, writer and reader tokens

SQLite may also create zigwiz.db-wal and zigwiz.db-shm while running. Do not remove those files from an open database. There is no separate SQLite installation or native npm SQLite addon to build: the adapter uses node:sqlite.

Custom location:

zigwiz start --home /path/to/zigwiz-home

The MCP endpoint is http://127.0.0.1:3100/mcp. The review app is http://127.0.0.1:3100/ (/admin is the same page): review the pending set, accept or reject each record, and write approved memory to configured Git Markdown or Confluence views. The first-party local browser can review without pasting a token in loopback-open mode. MCP remains a writer. Required-auth deployments use the admin token for human review. Ordinary start does not change client settings. Use zigwiz attach --clients codex,cursor (or claude,copilot,vscode,vscode-insiders) explicitly; add --dry-run to preview affected paths. Existing authentication settings are preserved. Client setup validates every selected file before writing and keeps backups. Direct Claude Desktop attachment is not included: its cloud connectors cannot reach this loopback endpoint, and its local extensions use a separate transport. See Claude’s connector documentation.

zigwiz install also installs the six source skills into the configured Codex skills directory. Use zigwiz skills install --target /path/to/skills for another host. zigwiz doctor compares source, built files, the running endpoint and installed skills; after updating the service or skills, open a new chat to reload its tools.

Discover business rules with agent hooks

zigwiz attach --clients codex,copilot,vscode
zigwiz skills install
zigwiz skills install --target "$HOME/.copilot/skills"
zigwiz hooks install --clients codex,copilot --repo /path/to/repo
zigwiz hooks status --repo /path/to/repo

Installation creates a repository scope from Git origin, or accepts --scope repository:existing-key to reuse an existing scope. Open /hooks in Codex to review the installed definitions, then start a fresh chat. The shared Copilot hook file supports CLI and VS Code. SessionStart supplies optional retrieval/discovery advice; Codex runs it in the background. Zigwiz installs no Stop hook and never forces a completion turn. Hooks fail open with bounded execution, and discovery can inspect at most eight relevant files and propose three implemented rules during ordinary work. Stable rule IDs reuse proposals and keep rejected facts from resurfacing unchanged. Nothing is approved automatically. No separate model or watcher runs.

zigwiz hooks remove --repo /path/to/repo disables discovery for that checkout. Installation supports macOS/Linux; hosts and the Zigwiz service must run on the same machine for the default loopback MCP endpoint. See hook setup and behavior.

Memory app and agent workflows

Open http://127.0.0.1:3100/ to review proposals. The Memory library pages through all active or archived records, shows full bodies and revision history, and supports new proposals, corrections, archive/restore and short-term promotion. Settings configures memory behavior, extraction and embedding providers, and applicability scopes. Search shows the top 20 active keyword matches; the graph and dashboard use bounded recent-memory samples.

Prompts & hooks offers five copyable workflows and their MCP prompt names: grill_me, memory_brief, checkpoint_task, remember_decision, and discover_rules. Interview prompts can resume an existing sessionKey. Repository discovery hooks are available for Codex and Copilot. Each repository opts in explicitly; the host agent proposes business rules from code and tests for human review.

For UI development, npm run preview starts a seeded disposable SQLite app at port 3101. It does not open the user's memory database or publish to external views. Stop it to remove the fixture. Set PREVIEW_PORT if needed.

Configure memory in the local UI

Serve the app with zigwiz start, or use npm run local from this checkout without installing the command. Open Settings. For a custom port, use the URL printed by the service and append /#settings. The UI is served by Zigwiz itself; no separate frontend process is needed.

• Memory behavior edits gathering, governance, source rules, retention, checkpoints, candidate limits, consolidation proposals, age weighting and optional semantic search. Policy saves apply immediately and reject stale revisions. Gathering starts disabled with strict review. Source rules must explicitly match a source, scope, authenticated credential ID and event type; deny rules win. Broader governance profiles allow only the source kinds and conditions approved by the administrator. Policies, decisions and checkpoint promotion still require review.
• Providers selects literal extraction (no model), Codex, Copilot, Cursor or an HTTP extraction gateway, plus an optional HTTP embedding gateway. The form saves only provider configuration in the active config.json, preserving storage, publication destinations and other settings. Restart the service to use provider changes. Native clients must already be installed and authenticated for the service account. Credentials stay in the service environment; enter their environment variable names in the form. Selecting a provider does not enable gathering.
• Workspace creates shared applicability scopes and shows the running storage, bind address, authentication and MCP settings. Runtime and publication configuration remain in the active config file or service environment. Scope labels do not make memory private.

Saving requires an administrator session. The first-party app has that role in loopback-open mode; required-auth deployments need an admin token. Provider settings are read-only when the server cannot safely update its active config file. Environment overrides are shown separately from saved configuration. A stale save must be reloaded before retrying so another editor's changes are preserved.

To try the forms with disposable data, run npm run preview and open http://127.0.0.1:3101/#settings. Preview changes belong to that temporary instance. See the settings API and memory policy and provider details.

A simple memory workflow

zigwiz scopes add repository:my-app "My app"
zigwiz status
# Or open http://127.0.0.1:3100/ to review all, then accept or reject each record,
# and write approved memory to Git Markdown or Confluence.
zigwiz review                       # Review all pending proposals first
zigwiz review PROPOSAL_ID           # Current revision, candidate and field changes
zigwiz accept PROPOSAL_ID           # Make this reviewed record active
zigwiz reject PROPOSAL_ID           # Discard this reviewed proposal (alias: revoke)
zigwiz sync VIEW_ID                 # Queue Git Markdown / Confluence publication
zigwiz search "database decision" --scope repository:my-app
zigwiz show MEMORY_ID               # Content and publication state
zigwiz forget MEMORY_ID             # Archive, retaining history and external views
zigwiz restore MEMORY_ID

Agents retrieve context, capture authorized knowledge, and propose corrections through MCP or the explicitly configured agent CLI/HTTP interface. Temporary observations are active immediately. Durable records become searchable after review. Repeated task checkpoints update one record per scope/session, preserving revision history and refreshing expiry. Archiving hides a memory from retrieval and prevents a view from reimporting it; it leaves Git files and Confluence pages intact.

Keep one focused record per useful decision, with its reason and evidence. Use revision proposals to correct existing records. Scope labels organize applicability; every record remains shared within the instance.

Run locally in one Docker container

From a fresh source checkout:

node scripts/setup.mjs --storage sqlite
docker compose -f compose.sqlite.yaml up --build -d
docker compose -f compose.sqlite.yaml logs -f memory

Only the memory service starts. The sqlite-data named volume persists /data/zigwiz.db and its journal files. The image remains non-root and publishes its port only on host loopback. Do not combine compose.sqlite.yaml with compose.yaml; they are standalone deployment choices.

For a native process using project-local configuration rather than ~/.zigwiz, run node scripts/setup.mjs followed by npm run dev. That profile stores the database at ./data/zigwiz.db.

Run with Postgres

From a fresh source checkout:

node scripts/setup.mjs --storage postgres
docker compose up --build -d
docker compose logs -f memory

The original two-service Compose deployment remains available. Only the application port is published; Postgres uses the postgres-data volume. Its initialization script creates a non-superuser memory application role. The database administrator password is not injected into the application container.

An existing v0.1 DATABASE_URL configuration continues to select Postgres unless storage is explicitly overridden. Existing PostgreSQL migrations are unchanged; v0.2 added runtime scheduling; v0.3 adds interview sessions and reversible memory archiving through new migrations. Do not delete database volumes when upgrading.

Setup never overwrites an existing .env or config.json. Re-running setup is not a provider switch or data migration. Select the correct profile in configuration and keep the matching credentials. SQLite-to-Postgres data transfer is not implemented yet.

Select storage

{
  "storage": {
    "provider": "sqlite",
    "path": "./zigwiz.db",
    "busyTimeoutMs": 5000
  },
  "views": []
}

Relative database paths resolve against the directory containing config.json. ~/ is expanded. STORAGE_PROVIDER overrides the configured provider; SQLITE_PATH overrides the SQLite path. For Postgres use storage.provider: "postgres" and DATABASE_URL. When no provider is set, a pre-existing DATABASE_URL selects Postgres; otherwise SQLite is the default. Invalid providers and in-memory service databases are rejected rather than silently falling back.

SQLite is a single-service, local-disk profile. Use Postgres for replicated services or substantial concurrent write workloads. See SQLite operations and backup.

Choose a view provider

Edit the views array in the active config. Storage and view provider are independent: both Git and Confluence work with either database.

Examples:

• SQLite only and SQLite plus Git.
• Git view, Confluence view, and mixed scopes/providers.

For native local mode, edit ~/.zigwiz/config.json and restart the process. For Docker, edit project config.json and recreate the selected Compose service. Existing view-only examples can be copied for Docker because each Compose file explicitly selects storage. For native mode preserve the storage object while copying a view example.

One active bidirectional view is supported per scope. View-configured scopes are created at startup. Different scopes may target distinct roots of the same Git repository.

Git prerequisites

The remote and configured branch must already exist with an initial commit. Use a dedicated managed root. Publication uses direct, non-force commits; a protected branch requiring a pull request will reject publication. PR creation is not implemented.

For HTTPS set GIT_CREDENTIAL_HOST, GIT_HTTP_USER, and GIT_HTTP_TOKEN; do not embed credentials in remote URLs. In native mode also set GIT_ASKPASS to the absolute path of scripts/git-askpass.mjs when using this helper. Docker configures it automatically. SSH requires suitable keys and verified known_hosts. Do not disable host-key checking.

The disposable cache is under the configured GIT_CACHE_DIR or the operating system's temporary directory. No repository scripts, hooks, external diff helpers, or submodules are executed. Local filesystem Git remotes require explicit allowLocal:true; this does not add arbitrary folder watching or repository auto-discovery.

Confluence prerequisites

Configure a Cloud site, space ID, and existing parent page ID. Set CONFLUENCE_EMAIL and CONFLUENCE_TOKEN. Only direct child pages are considered. Managed pages contain a metadata code block titled agent-memory/v1 and supported editable content. Unsupported structures become sync issues, not silent conversions.

Live Confluence has not been tested in this build environment. Draft checks are best effort, not an atomic editor lock. Validate with a sandbox space before using important knowledge.

Memory, tools, and approval

Supported scopes are organization, department, repository, and user. SQLite initializes organization:default and user:local; additional scopes can be created through the admin API.

The twelve MCP tools are memory_status, memory_policies, memory_scopes, memory_search, memory_get, memory_context, memory_capture, memory_propose_change, memory_checkpoint, memory_promote, memory_grill, and memory_discover. Five named prompts are also available.

memory_grill guides a contextual conversation about a repo or idea. The host agent reads available project evidence, approved memory and previous answers, starts with the intended user outcome, and recommends a direction with reasons and tradeoffs. Coverage tracks are optional: the agent prioritizes useful decisions and can wrap up early instead of walking through a fixed questionnaire. Zigwiz supplies state and memory; the host agent supplies synthesis, without a separate model call in the service.

start requires an idempotencyKey and returns a sessionKey, sequence, memory bodies, constraints, focus and transcript. Every later mutation requires expectedSequence from the latest response and a fresh idempotencyKey. Retry an uncertain request with the identical arguments/key. status needs only sessionKey. When needsPreparation is true, the agent calls prepare with context, one question, a recommendation and optional substantive choices, then shows its askQuestion in the host UI. Custom text is answer; a selected choice is choiceId; skip and wrap_up map to those actions. status restores the exact prepared question. Wrap-up includes a decision summary and recommended next step from the host, and proposes one durable record per answered track. The human reviews the full pending set in the app at GET / or with zigwiz review, then zigwiz accept ID or zigwiz reject ID (revoke alias) for each record. Interviewer advice is labeled separately from human answers. MCP never approves those writes. The authoritative session is one database row; answer, checkpoint and proposal writes are transactional. The answer limit is 90,000 characters and session limit 400,000, checked before partial writes. Old v1 checkpoints import once. Short-term state remains until TTL. HTTP equivalent: POST /api/grill; details and examples are in API documentation.

Short-term captures are immediately available and expire under their TTL. Durable agent captures become proposals. Review the pending set first, then accept or reject each record through the human CLI or HTTP management API; an administrator can also explicitly create an approved durable record. MCP never exposes approval, even with an administrator credential. The local deployment does not silently auto-approve agent writes.

Accepted durable records publish to their configured view, including user-scoped records. Short-term records stay in the canonical database because they expire, not because they are private. All API examples and review endpoints are in API documentation.

Agent skills

Skills define the workflow; the configured transport carries its requests. Begin with zigwiz-memory, which routes to zigwiz-retrieve, zigwiz-capture, and zigwiz-grill. zigwiz-discover handles authorized repository facts; zigwiz-mcp remains a compatibility alias. All sources live under .cursor/skills; they have no mandatory MCP dependency.

For approved CLI/HTTP environments, the operator provisions a non-secret agent.json:

{"version":1,"mode":"cli","enabledTransports":["cli"],"url":"http://127.0.0.1:3100"}

Select it with ZIGWIZ_AGENT_CONFIG; provision a reader/writer credential separately through ZIGWIZ_AGENT_TOKEN. The agent CLI never loads the service .env or management admin credential. Remote URLs require HTTPS. auto may choose only explicitly enabled transports; MCP being blocked is not permission to enable CLI.

zigwiz skills install --repo /path/to/repo --layout agents
zigwiz agent transport --json
zigwiz agent scopes
zigwiz agent context --input context.json --json
zigwiz agent checkpoint --input checkpoint.json
zigwiz agent capture --input decision.json
zigwiz doctor --agent-config /approved/agent.json --repo /path/to/repo --json

capture with lifetime:long_term returns a proposal for human review. There is no agent approval command. The agent endpoint rejects admin tokens and requires reader/writer bearer authentication even in local open mode. Human review remains in the app or management CLI/API.

Existing MCP clients continue using /mcp and the same twelve tools. An operator may set ZIGWIZ_MCP_ENABLED=false to disable MCP without affecting CLI memory. After changes, rebuild/restart, reinstall skills and open a fresh chat. See Agent Skills, deployment, security and migration.

Backup, tests, and development

Stop the native SQLite service, then create a new snapshot:

node scripts/zigwiz.mjs backup --home ~/.zigwiz --out /path/to/zigwiz-backup.db

The backup command refuses an active service and existing output files. It uses a consistent SQLite snapshot, not a copy of a live .db file. Back up configuration and credentials separately. See restore instructions.

npm test                  # Real SQLite, queue, HTTP/SDK, CLI, Git, recovery and retrieval checks
npm run test:sqlite       # SQLite-specific tests
npm run test:integration  # Requires TEST_DATABASE_URL for real Postgres/pg-boss
npm run check
npm run verify            # Regenerate current verification report and raw logs
node scripts/smoke-agent.mjs # Disposable real SQLite process, MCP disabled, agent + human CLI lifecycle

After dependencies are installed and a service is running, use the official MCP SDK smoke script. For native local mode:

node --env-file="$HOME/.zigwiz/.env" scripts/smoke.mjs

The checked-in lockfile is used by CLI installation, CI and Docker builds. dist/build-info.json records the source fingerprint, tool schema and skill versions. Verification distinguishes automated checks from external-provider and deployment acceptance. Optional embeddings, model services and additional infrastructure are not required.

Documentation

SQLite/local mode · Architecture · API · Operations · Verification · Roadmap · Changelog · References