Zharwing Memory

Zharwing Memory is a local-first project context manager for AI-assisted coding workflows. It is not the coding agent. External agents such as Codex, Claude Code, Gemini CLI, Ollama-based tools, LM Studio workflows, and future MCP-capable clients do the engineering work. Zharwing Memory provides their durable, project-scoped memory layer.

The product keeps project knowledge, AI session history, context bundles, diagrams, decisions, commands, gotchas, and optional review proposals organized per project. A human can open the local browser UI or native desktop app to understand current work, inspect AI context, inspect the graph, search previous work, and enable review workflows only when wanted.

Status: standalone personal developer preview. The current product is intended for a trusted developer using a local, single-user environment. It is not presented as a production, multi-tenant, or hardened harness release. See the developer preview boundary for the exact profile, limitations, compatibility policy, and validation gates.

The dependency-free public documentation website and its structured documentation portal are maintained in this repository. They explain the downloadable local application; they are not a hosted version of Memory and cannot access a user's memory store. The website source and maintenance guide remain available in the repository.

Current Implementation Status

This repository is the generic, project-neutral Zharwing Memory application source. Private user memory, project data, and personal workflows belong outside this repo in each user's chosen memory store.

Implemented:

• TypeScript monorepo layout.
• Local daemon API.
• CLI helper.
• MCP HTTP endpoint and stdio adapter.
• Tauri + React desktop shell.
• Markdown-first storage model.
• Project registry and .zharwing/memory.json pointer support.
• Project-scoped sessions and workstreams.
• Context bundle generation with inclusion/exclusion reasons.
• AI-visible project memory with explicit visibility exclusions, never-send rules, secret redaction, and high-risk blocking.
• Optional Memory Inbox proposals for review-mode or risky updates.
• Docs, diagrams, graph, search, backup snapshot, and rebuildable index boundaries.
• Optional local Memory Assistant boundary with deterministic jobs and reviewable proposal support.
• Generic Markdown folder importer with preview/commit flow for existing memory and session corpora.
• Flexible named repository links with custom role/category metadata.
• Desktop/web first-run flow for project-only and single-repo setup.
• Recoverable delete flow with global Trash, restore, and permanent purge actions.
• Lightweight desktop navigation with project switcher, primary sections, and section tabs.
• Configurable project graph rules for mapping imported folder layouts to topics, services, packages, diagram groups, and code areas without hardcoded project names.
• Optional semantic graph analysis for LLM-assisted relationship proposals, review/approval, accepted AI-reviewed graph overlays, and local OpenAI-compatible providers.

The Codex/MCP daily-memory loop is complete. The supported capabilities map to the focused MCP surface as follows:

Capability	Supported MCP tool
Resolve startup state	memory.get_startup_state
Read compact previous-work summaries	memory.get_startup_state, memory.get_latest_session, memory.get_recent_sessions
Read selected full session history	memory.get_session_detail
Start today's work record	memory.start_session
Search decisions, fixes, commands, and notes	memory.search
Save progress	memory.save_checkpoint
Record completion and next steps	memory.close_session

Context preview/load and health checks complete the eleven-tool surface. Project creation, repository linking, imports, graph settings, backups, and destructive operations remain administrative UI/CLI actions by design; they are not missing daily-memory features.

Validated in the current workspace:

• Workspace TypeScript build-mode validation passes.
• The root test command passes a deterministic spine covering privacy gates, Markdown session/document round-trips, context privacy integration, daemon lifecycle, graph overlays, semantic graph policy, and a fake OpenAI-compatible semantic graph provider flow.
• The daemon, CLI, MCP adapter, browser UI, and desktop UI are implemented.
• Optional semantic graph analysis is implemented for local OpenAI-compatible providers and can be smoke-tested manually.
• Graph context map, context, session, docs, import, inbox, backup, and trash workflows do not require an AI provider.

Validation still outstanding (separate from the completed Codex daily-memory surface):

• Broad end-to-end test coverage across all desktop workflows.
• Running the opt-in live-provider smoke against each provider configuration the project intends to support.
• Installer generation and installer-level smoke testing; the packaged Windows .exe build itself has passed.

Current Windows-checkout validation includes TypeScript typecheck, the complete test suite and coverage thresholds, desktop contract tests, the Vite production build with bundle budgets, a real Edge app-shell smoke, Rust tests, a packaged Windows executable, source-artifact checks, and a live eleven-tool MCP doctor check.

Product Principles

1. Project-scoped by default. Sessions, docs, graph, search, context, and startup state all resolve to the current project unless the user explicitly asks for all-project behavior.

2. Markdown is the source of truth. The supported index is a versioned, dependency-free JSON projection rebuilt from Markdown. SQLite/FTS5 remains an optional future optimization for very large stores, not unfinished core functionality.

3. UI, CLI, and MCP share daemon behavior. The daemon owns project/session/context logic. Each adapter exposes its intended surface without reimplementing the underlying rules; MCP stays focused on the daily agent-memory loop.

4. AI-visible by default. Memory in the selected project is available to the coding agent by default, including sessions, paths, and routine metadata. Explicit visibility exclusions, never-send patterns, and secret scanning remain safety rails.

5. Memory writes are direct by default. External AI agents can write routine session progress and durable project memory directly. Memory Inbox review is an optional project setting for teams that want approval gates or for risky/uncertain updates.

6. Session graph visibility is opt-in. Every session remains available in Session History, search, and eligible AI context. Routine sessions do not create graph nodes. A user can enable Include in graph from Work -> Sessions when a session is important enough to belong in the durable project map; its derived relationships are included with it.

Repository Layout

apps/
  desktop/          Shared React browser UI and Tauri human interface
  daemon/           Localhost JSON-RPC daemon
  cli/              zharwing-memory command-line helper
  mcp-server/       MCP-style stdio adapter

packages/
  core/             Domain types, policies, IDs, defaults
  storage/          Markdown storage, registry, sessions, docs, inbox, backups
  privacy/          Visibility gates, patterns, secret scanning, redaction
  context-engine/   Bundle selection, reasons, token estimates, markdown rendering
  search/           Dependency-free keyword search boundary
  graph/            Derived relationship graph
  semantic-graph/   Optional LLM-assisted relationship analysis and proposals
  assistant-runtime/Optional local assistant boundary
  api-client/       Shared daemon API client
  mcp-tools/        MCP tool definitions and dispatch
  theme/            Graphite + Copper design tokens

docs/
  README.md         Documentation index
  WEB_UI.md         Local browser startup, auth, usage, and troubleshooting
  ARCHITECTURE.md   System architecture
  DATA_MODEL.md     Entities, storage, and metadata
  API_REFERENCE.md  Daemon, CLI, and MCP surfaces
  MCP_SETUP.md      Codex, Claude, HTTP/stdio, auth, and troubleshooting
  AGENT_AUTOMATION.md MCP, bootstrap, and skill setup for agents
  USER_FLOWS.md     Human and agent workflows
  DESKTOP_UI.md     Desktop navigation and first-run flow
  GRAPH_RULES.md    Graph extraction rules for imported layouts
  SEMANTIC_GRAPH.md Optional LLM-assisted relationship analysis
  DIAGRAMS.md       Mermaid UML, ERD, sequence, state, flow diagrams
  OPERATIONS.md     Setup, runtime, backup, validation notes
  AI_TESTING.md     Manual AI-provider and semantic graph smoke tests

website/
  memory/           Dependency-free public documentation website

templates/
  bootstrap/        Generic AGENTS.md and CLAUDE.md templates for linked repos
  mcp/              Generic Codex and Claude MCP config examples
  skills/           Generic Zharwing Memory session skill template

First Run

Zharwing Memory separates application source code from private memory data.

llm-memory/
  project/   app source code, safe to clone and version
  store/     private local memory data, do not commit

Other users should clone only the app source, then choose their own private store path.

corepack pnpm install
cp .env.example .env

Edit .env:

ZHARWING_MEMORY_ROOT=<absolute-private-store-path>
ZHARWING_MEMORY_AUTH_TOKEN=<local-random-token>
VITE_ZHARWING_MEMORY_AUTH_TOKEN=<same-local-random-token>

Local Browser UI

The browser UI is a complete local interface for normal daily use, not a demo or a reduced documentation view. It exposes the same React pages and workflows as the native desktop window.

Start the daemon in the first terminal:

corepack pnpm dev:daemon

Start the browser UI in a second terminal:

corepack pnpm dev:web

Open http://localhost:5174/. Keep both processes running. The browser UI calls the daemon at http://127.0.0.1:37841; dev:web does not start it.

The values of ZHARWING_MEMORY_AUTH_TOKEN and VITE_ZHARWING_MEMORY_AUTH_TOKEN must match. Restart dev:web after changing Vite environment variables. Browser path fields accept typed or pasted absolute paths because browsers cannot expose arbitrary local folders.

See the dedicated Browser UI guide for the full setup, browser-versus-desktop comparison, local authentication, and troubleshooting.

Native Desktop UI

For the native Tauri app, run:

corepack pnpm dev:desktop

In a source checkout, the desktop shell starts or reuses the local daemon automatically. A copied release executable reuses an already-running daemon or uses ZHARWING_MEMORY_DESKTOP_DAEMON_COMMAND when configured. The native shell adds OS folder pickers; the core project, session, library, graph, and settings workflows are shared with the browser UI.

In either UI, create a project, then link repos from Repositories. For multi-repo products, create the project first and add each Git repo root afterward.

Pointer Files

A pointer file is a small .zharwing/memory.json file that Zharwing Memory can write into a linked Git repo. It lets tools opened from that repo detect the matching memory project automatically.

Example:

{
  "projectId": "my-project",
  "memoryRoot": "<absolute-path-to-private-memory-store>"
}

When creating a project with Project only, the preview shows Pointer file: disabled because no repo is linked yet. Create the project first, then open Repositories, link each repo root, and leave pointer files enabled if you want agents and CLI tools to auto-detect the project from those repos.

To migrate existing Markdown memory, open Import after selecting the project. Use Memory Docs for old MEMORY folders, Session History for old SESSIONS folders, and Mixed Workspace when one folder contains both. Preview first; commit only after the counts and sample rows look right.

After importing, use Graph Rules when the imported folder layout should create context hubs in the Graph page. Open Settings -> Project -> Graph Rules and save a JSON array such as:

[
  { "match": "apps/*", "nodeType": "package", "topic": "frontend" },
  { "match": "services/*", "nodeType": "service", "topic": "backend" }
]

This is project configuration, not application hardcoding. Zharwing Memory matches rules against imported relative paths and derives context graph nodes from them. Imported documents participate normally. Imported sessions remain searchable history and default to Include in graph off; enable it per session before session metadata or its imported path contributes to the graph. Use Graph for memory relationships; use Diagrams for runtime architecture and service dependencies. See Graph Rules for the full manual and AI-assisted administration workflow.

For AI-assisted relationship cleanup, use the optional semantic graph workflow. Graph works without a model and shows trusted saved relationships. AI review creates Inbox proposals; accepted relationships then appear in Graph. See Semantic Graph Analysis.

LM Studio or another local OpenAI-compatible provider is needed only for provider checks, model-backed session TLDR generation, and model-backed semantic graph analysis. It is not required for normal validation, daemon startup, context preview, or Graph viewing. See Testing With AI Providers.

Never commit the memory store. It contains project sessions, docs, imports, context bundles, Memory Inbox proposals, and backups.

Deletion is recoverable by default. Projects, linked repo entries, workstreams, sessions, docs, inbox proposals, and backups move to Trash first. Trash supports restore, single-item permanent delete, selected permanent delete, and full empty.

Architecture Summary

Browser UI     \
Desktop UI      \
CLI              -> daemon API -> shared packages -> Markdown source of truth
MCP adapter     /                              \-> rebuildable indexes

The daemon owns:

• project detection
• project creation/linking
• session start/resume/list/checkpoint/close
• context bundle preview and generation
• project scope, explicit visibility exclusions, and secret checks
• Memory Inbox proposals
• docs and diagrams
• search
• graph projection
• backup and validation
• trash, restore, and permanent purge
• optional assistant jobs

The browser UI, native desktop app, CLI, and MCP server are adapters.

Memory Root Shape

The memory root is private per-user state. It can live anywhere on the local machine and is configured with ZHARWING_MEMORY_ROOT.

Zharwing Memory Root/
  global/
    projects.json
    trash/
  projects/
    <project-slug>/
      project.json
      overview.md
      architecture.md
      decisions.md
      tasks.md
      gotchas.md
      commands.md
      glossary.md
      privacy.md
      sessions/
      workstreams/
      docs/
      assets/
      generated/
      inbox/
      semantic-graph/
      audit/
      backups/

Repos may contain:

.zharwing/memory.json

That pointer file contains project identity, the machine-local memory location, and compact context-selection limits used during project detection. Because the memory location is machine-local, .zharwing/memory.json is ignored by this app repo by default. Teams can decide separately whether pointer files in their own linked repos should be committed or kept local.

Main Workflow

1. Create or link a project.
2. Read the latest relevant previous session.
3. Start a fresh project-scoped session for the current day or work round.
4. Preview or load the AI context bundle when prior context is useful.
5. External AI performs coding work.
6. AI saves checkpoints after meaningful progress.
7. AI closes the session with next steps.
8. AI writes durable memory directly when review mode is off.
9. Review-mode or risky updates go to the Memory Inbox for accept/edit/reject/deferral.

Agent Automation

For automatic session behavior in Codex, Claude, or local agents:

1. Start the daemon.
2. Register the MCP adapter with zharwing-memory mcp install auto.
3. Link source repos from the UI or CLI. For multi-repo projects, keep Write pointer file enabled for every repo and open a separate Codex workspace for each repo being actively changed.
4. Generate repo bootstrap files from templates/bootstrap/.
5. Optionally install templates/skills/ai-memory-session as a generic Codex skill or translate it into another agent's custom instruction format.

Agents should call memory.get_startup_state once per work round, use its compact carry-forward summaries, start a fresh daily/work-round session, search memory, request selected session detail or context only when needed, save checkpoints during work, and close or checkpoint at the end. See Agent Automation. See Repository Links for the shared-memory, separate-workspace multi-repo pattern.

For localhost-only personal setups, ZHARWING_MEMORY_AUTH_MODE=none lets MCP clients use http://127.0.0.1:37841/mcp without a bearer token. The daemon refuses no-auth mode on non-loopback hosts.

For MCP setup details, including Codex and Claude config, HTTP vs stdio, Windows/WSL reachability, desktop installer buttons, and troubleshooting, see MCP Setup.

CLI Examples

The CLI assumes the daemon is running.

zharwing-memory init <repo-root> --name "My App" --bootstrap AGENTS.md,CLAUDE.md
zharwing-memory projects
zharwing-memory status --project my-app
zharwing-memory repos --project my-app
zharwing-memory link-repo <repo-root> --project my-app --name "Service API" --role service
zharwing-memory create-workstream "Huddle" --project my-app --topic huddle,realtime
zharwing-memory workstreams --project my-app
zharwing-memory start "Fix settings page save bug" --project my-app --agent codex
zharwing-memory sessions --project my-app
zharwing-memory session session-id --project my-app --section body
zharwing-memory context --project my-app --preview
zharwing-memory checkpoint --project my-app --session session-id "Implemented save flow"
zharwing-memory close --project my-app --session session-id "Save bug fixed"
zharwing-memory inbox --project my-app
zharwing-memory search --project my-app "settings save"
zharwing-memory graph --project my-app
zharwing-memory backup --project my-app
zharwing-memory validate --project my-app
zharwing-memory rebuild-index --project my-app
zharwing-memory import-profiles
zharwing-memory import-folder <source-memory-folder> --project my-app --profile markdown-memory
zharwing-memory import-folder <source-sessions-folder> --project my-app --profile markdown-sessions --commit

Assistant proposal examples:

zharwing-memory assistant status --project my-app
zharwing-memory assistant summarize-session --project my-app --session session-id
zharwing-memory assistant generate-session-summary --project my-app --session session-id
zharwing-memory assistant generate-session-summaries --project my-app
zharwing-memory assistant generate-session-summaries --project my-app --all
zharwing-memory assistant return-summary --project my-app
zharwing-memory assistant classify-doc --project my-app --doc doc-id

MCP Tools

The MCP adapter exposes exactly eleven project-scoped tools for the daily coding-memory loop:

• memory.health
• memory.get_startup_state
• memory.get_latest_session
• memory.get_recent_sessions
• memory.get_session_detail
• memory.start_session
• memory.search
• memory.preview_context_bundle
• memory.get_context_bundle
• memory.save_checkpoint
• memory.close_session

The full daemon API is intentionally broader. Use the desktop UI or CLI for project administration, repository links, workstreams, document editing, imports, graph settings, backups, Trash, and other administrative operations. See API Reference for both surfaces.

Browser And Desktop UI

The local browser UI and native desktop app share the same React human interface. The browser UI is often the fastest way to use Memory from a source checkout: run the daemon, run dev:web, and open http://localhost:5174/. The sidebar stays intentionally small:

• project switcher for selecting, creating, and deleting projects
• Dashboard
• Repos
• Work
• Library
• Import
• Search
• Trash
• Settings

Secondary pages live inside section tabs:

• Work: Current Work, Sessions, Workstreams
• Library: Docs, Diagrams, Inbox, Graph, Context
• Settings: Project, Setup, Assistant, Backups

In the native Tauri desktop window, Setup, Repositories, and Import provide Browse buttons for selecting folders with the OS file picker. The browser UI provides the same underlying workflows but uses typed or pasted absolute paths because browsers do not expose arbitrary local folder paths to web apps.

See Browser UI for startup and troubleshooting, and Browser And Desktop UI for navigation and first-run flow.

The visual direction follows the Graphite + Copper theme from the product plan.

Documentation

Start here:

• Public Documentation Website Source
• Developer Preview Boundary
• Documentation Index
• Architecture
• Data Model
• API Reference
• User Flows
• Browser UI
• Browser And Desktop UI
• Graph Rules
• Diagrams
• Operations
• Testing With AI Providers
• MVP Walkthrough

Implementation Notes

• Install dependencies in the same operating system that will run Vite/build commands; shared Windows/WSL checkouts can otherwise keep the wrong native Vite/Rollup/esbuild optional package.
• Mermaid diagrams are stored as Markdown and are intended to render in Mermaid-capable viewers.
• The assistant runtime can generate searchable session TLDR metadata through a configured local OpenAI-compatible endpoint, with deterministic fallback. It does not download or run a model.
• The versioned JSON index is a supported rebuildable project manifest. Search continues to read Markdown-backed project records; SQLite/FTS5 is optional future scaling work.

License

Apache License 2.0 — see LICENSE. Security reports: see SECURITY.md.