Skip to content

README.md

Latest commit

 

History

History
140 lines (105 loc) · 6.48 KB

README.md

File metadata and controls

140 lines (105 loc) · 6.48 KB
Raw

Zharwing Memory Documentation

This folder contains product and engineering documentation for the Zharwing Memory implementation.

Core Docs

  • Setup Supported runtimes, local profiles, browser/desktop startup, agent boundary, and public documentation generation.

  • Frontend V2 Implementation Status Current browser/desktop architecture and an explicit separation between implemented source and release/device qualification.

  • Developer Preview Boundary Implemented personal-preview and hardened-local profiles, limitations, migration boundary, and claim rules.

  • Architecture System boundaries, runtime structure, package responsibilities, and context safety flow.

  • Data Model Project, session, document, proposal, context bundle, graph, and storage entities.

  • API Reference Daemon JSON-RPC methods, CLI commands, MCP tools, and prompt resources.

  • Agent Protocol Project-neutral workflow for any AI agent using Zharwing Memory, plus adapter boundaries.

  • Agent Automation MCP setup, repo bootstrap files, skill template, and automatic session workflow.

  • MCP Setup Codex, Claude Code, Claude Desktop, HTTP vs stdio, auth modes, Windows/WSL, and troubleshooting.

  • Repositories Flexible multi-repo project links, names, descriptions, pointer files, CLI commands, and daemon administration methods.

  • Workstreams Multi-day topic/epic grouping for related sessions, docs, and imported memory.

  • User Flows First-time setup, daily coding, project return, context preview, inbox review, assistant workflows, backup, and recovery.

  • Browser UI Cookie/CSRF browser authority, explicit local preview startup, hardened bootstrap requirements, browser-versus-desktop differences, and recovery.

  • Browser And Desktop UI Shared navigation, browser and Tauri runtime modes, first-run setup, import workflow, opt-in session graph visibility, and Trash behavior.

  • Diagrams Mermaid diagrams: architecture, UML class diagram, ERD, sequence diagrams, state machines, user flow, context pipeline, storage layout, and backup flow.

  • Operations Runtime assumptions, configuration, startup, backup, validation, indexing, security, and known constraints.

  • Testing Plan Exact frontend commands, source coverage, integrated gate order, and the boundary between CI, local source completion, and release/device evidence.

  • Frontend V2 Migration Profile selection, role credentials, visibility, preferences, graph layout, compatibility windows, and rollback.

  • Frontend V2 Compatibility Register Dated retained/removed compatibility paths, active callers, removal proof, and residual risk.

  • Frontend Qualification Matrix What each surface has actually been tested against, which gates have not been run, what still needs a real device, and the rules for claiming a release.

  • Testing With AI Providers Manual LM Studio/Ollama/llama.cpp-style provider checks, session TLDR tests, and semantic graph smoke tests.

  • Importing Generic Markdown import profiles, preview/commit workflow, CLI examples, and daemon administration usage.

  • Graph Rules Manual and AI-assisted administration workflows for mapping imported folder layouts into useful context graph nodes, including the opt-in rule for session nodes.

  • Semantic Graph Analysis Optional LLM-assisted relationship analysis, review modes, local provider setup, approval flow, and storage.

  • MVP Walkthrough Quick command-oriented walkthrough of the core MVP loop.

  • Source And Context Boundary Explicit public-source allowlist, generated direct pages, bounded search projection, synthetic evidence, and private-context exclusions.

  • Architecture Decision Records Durable local-first, progressive-documentation, and project-bound-authority decisions with their context and consequences.

Reading Order

  1. Read the root README.
  2. Use Setup to choose a profile and start the intended surface.
  3. Read Frontend V2 Implementation Status and Developer Preview before making a readiness claim.
  4. Read Architecture and Diagrams.
  5. Use Browser UI and Browser And Desktop UI for human-interface setup and operation.
  6. Use Frontend V2 Migration before changing a profile, credential, visibility default, or persisted cache.
  7. Use Testing and the Qualification Matrix before any source-complete or release/device claim.
  8. Continue with the domain guides below for agent, repository, import, graph, provider, and operations work.
  9. Read Source And Context Boundary before changing the public website, its direct pages, or its search index.
  10. Add durable boundary decisions to the Architecture Decision Records.

About EXECUTION/ References

Some planning documents (the implementation blueprints and their baselines) reference files under EXECUTION/. That directory is the local orchestration workspace - work-package queues and implementation state used to drive AI implementation agents during development. It is deliberately not shipped in this repository: its contents are session-scoped working state, not product documentation. The blueprints remain readable without it; treat those references as pointers into the development process, not into this tree.

Documentation Policy

  • Diagrams are Mermaid-first so they remain editable Markdown.
  • Storage documentation treats Markdown as durable source of truth.
  • Generated or assistant-proposed documentation follows the project's memory write mode: direct by default, with Memory Inbox review available when the project enables it or the update is risky or uncertain.
  • Project-scoped behavior should be documented explicitly whenever a feature could otherwise be confused with global behavior.