memorix 1.1.13 → 1.2.0

package/docs/1.2.0-CLAIM-LEDGER.md

@@ -0,0 +1,72 @@
+# Memorix 1.2 Claim Ledger
+
+The Claim Ledger is the first layer of the 1.2 Knowledge Workspace. It turns a
+small, source-qualified statement into something Memorix can safely retrieve,
+review, supersede, or warn about.
+
+It is not a generated knowledge graph and it is not a replacement for code,
+Git, tests, or the original memory. A claim is useful only because its evidence
+is still inspectable.
+
+## What a claim records
+
+| Field | Meaning |
+| --- | --- |
+| subject, predicate, object | One compact project assertion |
+| scope | Project, workspace, team, workflow, or task boundary |
+| evidence | Observation, Git, code, test, document, workflow, or run references |
+| snapshotId | The Code State Snapshot that qualified code evidence |
+| confidence | Bounded source-quality signal, never a statement of certainty |
+| status | active, superseded, disputed, or unknown |
+| reviewState | approved, needs-review, draft, or rejected |
+
+SQLite is the local operational index. Evidence is referenced by ids, paths,
+and hashes; Memorix does not copy a second raw source tree or a full chat log
+into the ledger.
+
+## Automatic policy
+
+Memorix derives low-risk claims only from:
+
+1. an explicit user or agent memory; or
+2. Git-ingested evidence.
+
+It does not promote ordinary hook output, model-generated summaries, or every
+conversation fragment into a project fact. Model-origin claims stay draft or
+need review until a user or agent explicitly reviews them.
+
+When an explicit observation names current code, its claim receives both the
+observation evidence and the matching code-reference evidence. New references
+inherit the latest completed Code State Snapshot at bind time.
+
+## Conflict and supersession
+
+Two approved active assertions with the same subject, predicate, and scope but
+different values are marked disputed together. Memorix keeps both; the newest
+write never erases the other side.
+
+Supersession is explicit and evidence-aware. A replacement claim must address
+the same project assertion and a source reference must explain the transition.
+The old claim remains in the audit trail with its replacement id and validity
+end time.
+
+## Dynamic qualification
+
+After a Lite CodeGraph refresh:
+
+- a deleted or changed bound symbol makes a claim unknown and needs-review;
+- a changed bound file lowers confidence and asks for review;
+- an incomplete scan lowers the confidence of code-bound claims instead of
+  presenting them as complete truth.
+
+The refresh still succeeds if ledger qualification cannot run. Memorix reports
+that the qualification was skipped and preserves the source memory rather than
+discarding a user write.
+
+## Retrieval boundary
+
+The ledger already exposes a deterministic, task-lensed selector internally.
+It returns only matching source-qualified claims, carries conflicts as cautions,
+and obeys a token budget. The user-facing Knowledge Workspace, canonical wiki
+pages, and advanced operator commands arrive in the next phases; they will use
+this ledger rather than treating generated prose as source truth.

package/docs/1.2.0-CODE-STATE.md

@@ -0,0 +1,61 @@
+# Memorix 1.2 Code State Snapshots
+
+Code State Snapshots give Memorix a bounded answer to a basic question:
+which version of the project did this memory or structural fact describe?
+
+They do not copy project source into a second database. A snapshot stores Git
+metadata, a worktree fingerprint, and scan completeness. Structural facts keep
+their normal hashes and receive the snapshot id and source epoch that last
+confirmed them.
+
+## Snapshot Contract
+
+| Field | Meaning |
+| --- | --- |
+| baseRevision | Full Git revision when Git can provide one |
+| worktreeState | clean, dirty, or unavailable |
+| worktreeFingerprint | SHA-256 of bounded Git revision and status metadata |
+| changedPathCount | Number of dirty Git paths, not their contents |
+| sourceEpoch | Monotonic project-local scan generation |
+| completeness | File cap, changed/removed counts, oversized skips, and deferred deletion checks |
+| previousSnapshotId | Prior completed scan for the same project |
+
+Git unavailable is an explicit unavailable state. It is never formatted as a
+clean worktree.
+
+## Lifecycle
+
+1. Lite refresh reconciles changed, unchanged, removed, and oversized files.
+2. Memorix reads bounded Git revision and porcelain status metadata.
+3. A transactional snapshot record is appended with the next source epoch.
+4. Current files, symbols, edges, and current observation-code refs point to
+   that snapshot.
+5. Project Context and codegraph status expose the latest snapshot rather than
+   silently treating an old scan as current.
+
+The snapshot is written after refresh reconciliation. An interrupted scan can
+leave no new snapshot, but cannot claim a partially written snapshot is
+complete.
+
+## Migration and Privacy
+
+The 1.2 migration is additive. Existing CodeGraph tables and rows remain in
+place; the migration adds snapshot columns and a code_state_snapshots table.
+Migration ids are recorded in schema_migrations.
+
+Snapshot records contain no source text, conversation content, credentials, or
+dirty path names. They only retain the fingerprint and aggregate counts needed
+to qualify later retrieval.
+
+## Operator View
+
+Use the existing commands:
+
+~~~powershell
+memorix codegraph refresh --json
+memorix codegraph status
+~~~
+
+The status output now includes revision availability, dirty state, changed path
+count, source epoch, and whether scan limits made the latest snapshot
+incomplete.

package/docs/1.2.0-DEVELOPMENT-CHARTER.md

@@ -0,0 +1,255 @@
+# Memorix 1.2 Development Charter
+
+Status: active development baseline  
+Branch: `codex/1.2.0-multidimensional-memory`  
+Start: 2026-07-17
+
+## Read This First
+
+[The 1.2 Product Story](1.2.0-PRODUCT-STORY.md) explains the user-facing
+promise and delivery narrative in plain language. This charter is the technical
+contract that keeps that promise honest.
+
+[Knowledge and Workflow Research](1.2.0-KNOWLEDGE-WORKFLOW-RESEARCH.md)
+records the external design study and the adopted boundary for project knowledge
+and workflow inheritance.
+
+[The 1.2 Implementation Plan](1.2.0-IMPLEMENTATION-PLAN.md) is the execution
+contract for the complete goal: data contracts, phase gates, compatibility,
+verification, and release criteria.
+
+## Product Direction
+
+Memorix 1.2 is not a larger text-memory product. Strong coding agents can
+often reread a repository faster and more accurately than they can sift
+through a long history of prose. Text memory still matters for decisions,
+constraints, and hard-won lessons, but it must earn a place in context.
+
+The 1.2 product is a **task-ready working context layer**. It combines four
+different kinds of evidence and returns only the compact workset that helps an
+agent act:
+
+1. **Narrative memory**: decisions, problems, constraints, and handoffs.
+2. **Code state**: current files, symbols, relations, and their freshness.
+3. **Change evidence**: Git commits, dirty-worktree facts, and lifecycle
+   signals that explain what has moved since a memory was captured.
+4. **Verification evidence**: relevant tests, commands, failures, and known
+   risks.
+
+The agent-facing experience stays simple: a natural-language task reaches
+`memorix_project_context`, and Memorix decides whether there is useful context
+to return. Users should not need to remember a graph command, a retrieval
+mode, or a storage model.
+
+## Current Baseline
+
+1.1 already has useful foundations:
+
+- SQLite-backed code files, symbols, edges, and observation-code references.
+- Incremental CodeGraph Lite refresh with hashes, deletes, size limits, and
+  built-in support for TypeScript, JavaScript, Python, Go, Rust, Java, C#,
+  C/C++, PHP, Ruby, and Kotlin at best-effort structural fidelity.
+- Code-reference freshness (`current`, `suspect`, `stale`, `unbound`).
+- Task lenses, current project facts, Code Memory status, bounded context packs,
+  Git Memory, and durable background maintenance.
+
+The current dashboard Knowledge Base and Knowledge Graph are useful projections
+of memories, mini-skills, and explicit relations. They are not a temporal
+semantic knowledge graph: their inferred relations are largely deterministic
+entity/category links. The 1.2 Claim Ledger and Knowledge Workspace now add
+claim-level validity, contradiction handling, review state, and a readable
+artifact layer. Existing workspace sync remains a compatibility converter;
+canonical workflow inheritance now lives in the Knowledge Workspace and uses
+safe, project-scoped adapters.
+
+That is a foundation, not the 1.2 finish line. Lite currently uses conservative
+language profiles and regex extraction, its graph does not yet represent a
+versioned code-state contract, and the product cannot yet prove that a returned
+workset reduced exploration or risk for the task.
+
+## 1.2 Invariants
+
+- **Memory earns context.** Do not inject a memory just because it exists.
+  It must be relevant, current enough, and actionable.
+- **Structure is not prose.** Code state stays normalized and versioned; a
+  narrative observation may reference it but cannot become the canonical graph.
+- **Dynamic means evidence changes with the project.** A workset is tied to a
+  repository revision and worktree fingerprint. Changed or deleted code
+  invalidates confidence rather than silently surviving as a fact.
+- **External tools are accelerators, not prerequisites.** When a healthy local
+  CodeGraph-class provider exists, Memorix can consume normalized evidence from
+  it. A project remains useful without one.
+- **No context dump.** The default return is an action map: where to start,
+  what is reliable, what changed, what is uncertain, and how to verify.
+- **No fake black box.** The user experience is quiet, but every suggested
+  fact carries provenance and freshness for agents and diagnostics.
+- **Knowledge is an artifact, not a label.** A wiki page has source-backed
+  claims, review state, and a drill-down path to evidence. A dashboard summary
+  alone is not an LLM Wiki.
+- **Workflow is protocol, not prompt ballast.** A reusable project playbook has
+  a trigger, phases, guardrails, and verification gates. It is delivered by
+  progressive disclosure and never silently rewrites project process.
+
+## Core Data Contract
+
+1.2 introduces a versioned `CodeStateSnapshot` around the existing code tables:
+
+```text
+CodeStateSnapshot
+  projectId
+  provider
+  baseRevision          Git HEAD when known
+  worktreeFingerprint   tracked dirty/untracked state summary
+  indexedAt
+  completeness          files/paths skipped, parser coverage, limits reached
+  sourceEpoch           invalidates older derived facts
+```
+
+`CodeStateSnapshot` does not duplicate source files. It records the provenance
+and completeness needed to decide whether symbols, edges, and memory bindings
+are still safe to use.
+
+The retrieval product is a `Workset`:
+
+```text
+Workset
+  task and task lens
+  start points            files/symbols with reasons
+  current evidence        code and Git facts
+  durable knowledge       only relevant narrative memory
+  cautions                stale, incomplete, contradictory, or low-confidence items
+  verification plan       focused tests/commands and why they matter
+  provenance              snapshot/revision/source refs
+```
+
+The Knowledge Workspace adds a claim and artifact layer above the existing
+stores:
+
+```text
+KnowledgeClaim
+  subject / predicate / object-or-value
+  sourceRefs / codeRefs
+  observedAt / validFrom / validTo
+  status                 active, superseded, disputed, unknown
+  confidence
+
+WikiPage
+  stable id, title, kind, frontmatter
+  claim refs, source refs, code-state reference
+  review state, links, updatedAt
+
+WorkflowSpec
+  trigger, assumptions, ordered phases
+  guardrails, expected output, verification gates
+  evidence refs and target-agent adapters
+
+WorkflowRun
+  selected workflow and task snapshot
+  evidence used, outcome, verification result
+```
+
+## Delivery Phases
+
+### Phase 0: Evidence and Evaluation
+
+- Define fixture repositories across supported languages and common project
+  shapes.
+- Record baseline measurements for memory-only context, broad repo rereads, and
+  current 1.1 context packs.
+- Establish release gates: freshness correctness, bounded first-turn latency,
+  no raw source dump, and no secret persistence.
+
+### Phase 1: Versioned Code State
+
+- Add snapshot metadata, source epochs, Git revision, and dirty-worktree
+  fingerprints to the code-state store.
+- Make refresh results explicit about completeness and skipped sources.
+- Invalidate derived refs by state transition rather than scan age alone.
+
+### Phase 2: Claim Ledger
+
+- Add source-backed claim records with temporal validity, supersession,
+  contradiction, and confidence semantics.
+- Require every claim to drill down to evidence and, when relevant, the
+  CodeStateSnapshot that qualified its code references.
+- Keep claims compact and typed; a generated graph edge alone is not a claim.
+
+### Phase 3: Wiki Compiler
+
+- Compile approved project evidence into interlinked Markdown wiki pages with
+  an index, evolution log, and lint checks.
+- Keep the human-readable wiki artifact separate from the local search index.
+
+### Phase 4: Workflow Inheritance
+
+- Add canonical project playbooks with triggers, phases, guardrails, outputs,
+  verification gates, and evidence refs.
+- Adapt one project-owned workflow to supported agent skill/rule formats rather
+  than treating a source-agent workflow format as canonical.
+- Record workflow runs and let repeated verified outcomes propose, but not
+  silently apply, workflow improvements.
+
+### Phase 5: Workset Retrieval
+
+- Turn `memorix_project_context` into the primary workset surface while keeping
+  its micro tool profile small.
+- Rank code state, Git evidence, narrative memory, and verification hints by
+  task, freshness, confidence, and token budget.
+- Return minimal context when Memorix has no meaningful advantage over a normal
+  file read.
+
+### Phase 6: Dynamic Lifecycle
+
+- Connect Git/hook/worktree changes to bounded refresh scheduling.
+- Preserve the 1.1 non-blocking handshake model: foreground context never waits
+  for a corpus-sized scan or remote provider request.
+- Add health and recovery diagnostics for stale snapshots and provider drift.
+
+### Phase 7: Parser and Provider Quality
+
+- Introduce a provider contract that normalizes symbols, relations, locations,
+  parser coverage, and confidence.
+- Replace regex-only structural extraction with a parser-backed provider after a
+  Windows/package-size benchmark. Tree-sitter is a candidate, not an unchecked
+  dependency decision.
+- Add an external-provider adapter only after its input can be validated,
+  versioned, and downgraded safely to the internal provider.
+
+### Phase 8: Product Validation
+
+- Compare new-agent task completion with and without a Workset across coding,
+  debugging, onboarding, refactor, and non-code tasks.
+- Measure broad scans avoided, stale-context catches, first useful action time,
+  and unnecessary-token cost.
+- Make dashboard and doctor explain evidence quality without exposing users to
+  internal storage jargon.
+
+## Non-Goals
+
+- Building a full IDE or language server inside Memorix.
+- Copying another CodeGraph product's API surface or asking users to operate two
+  memory systems manually.
+- Capturing every chat transcript or treating volume as memory quality.
+- Increasing MCP tool count to expose every graph primitive.
+- Claiming universal language precision before parser coverage and evaluations
+  prove it.
+- Calling the current memory visualization a full semantic knowledge graph or
+  calling a generated overview a maintained wiki before the artifact and claim
+  contracts exist.
+
+## First Implementation Slice
+
+The first 1.2 code slice is **Phase 0 plus the `CodeStateSnapshot` schema**.
+It must add no visible tool explosion and must prove these behaviors with
+fixtures:
+
+1. the same repository at a new commit produces a new snapshot;
+2. a dirty worktree is distinguishable from a clean commit state;
+3. an incomplete scan is visible and cannot be presented as complete truth;
+4. a task workset keeps only source-backed, current, or explicitly cautioned
+   items within its token budget.
+
+Only after those guarantees are tested should parser dependencies or external
+CodeGraph adapters enter the runtime. The claim ledger, wiki compiler, and
+workflow inheritance begin only after code-state evidence can state its own
+completeness and revision.

package/docs/1.2.0-DYNAMIC-LIFECYCLE.md

@@ -0,0 +1,71 @@
+# Memorix 1.2 Dynamic Lifecycle
+
+"Dynamic" in Memorix does not mean doing a full scan or an LLM call whenever
+an agent asks a question. It means durable evidence is requalified after the
+project changes, through bounded background work that can recover from a
+stopped client.
+
+## Foreground boundary
+
+Project Context and Context Pack read the latest completed local state. They
+may enqueue work, but they never wait for:
+
+- a repository-sized Code Memory scan;
+- claim requalification;
+- knowledge compilation or lint;
+- workflow file indexing; or
+- a provider or model request.
+
+If a new scan is needed, the Workset says what is currently known and marks
+the relevant state as dirty, incomplete, suspect, or stale.
+
+## Durable jobs
+
+The existing SQLite maintenance ledger owns all lifecycle jobs. 1.2 adds:
+
+| Job | Trigger | Result |
+| --- | --- | --- |
+| codegraph-refresh | stale/missing index, hook, startup | New CodeStateSnapshot |
+| claim-derive | explicit or Git-backed memory write | Source-qualified claim evidence is produced after the memory write has completed |
+| claim-requalification | after a completed code refresh | Claims are rebound to current code, then become current, needs-review, or unknown from that evidence |
+| knowledge-compile | explicit knowledge-producing write or refresh | Local workspaces receive reviewable proposals |
+| knowledge-lint | code/claim/workspace lifecycle event | Broken, stale, conflicting, or manually protected artifacts become visible |
+| workflow-index | startup or workspace lifecycle event | Canonical Markdown workflow metadata is refreshed in SQLite |
+
+Jobs have a project id, dedupe key, retry budget, lease, sanitized error
+record, and bounded payload. A duplicate event updates the existing active job
+instead of starting a second full pass.
+
+The dedupe key is deliberately stable per project and job kind. A newer hook,
+manual refresh, or startup check replaces an active job's payload; it does not
+create one expensive pass per CodeStateSnapshot.
+
+Code Memory refreshes are scheduled from project startup, Project Context,
+session startup, and a supported agent's real file-mutation hook. A file edit
+only records a small durable queue entry; it never parses the repository inside
+the hook process.
+
+## Write policy
+
+The lifecycle worker may update SQLite state and local/private Knowledge
+Workspace proposals. It never automatically applies a proposal to a published
+page.
+
+When both kinds of workspace exist, lifecycle reads target the same versioned
+workspace preferred by the Task Workset. A payload may explicitly target the
+local or versioned workspace. For a versioned workspace, background compilation
+is disabled unless an explicit operator payload permits it; indexing and linting
+remain read-only against project Markdown. This prevents a background process
+from creating unexpected Git changes merely because an agent opened a project.
+
+## Recovery and visibility
+
+Workers use SQLite leases. A process that exits while holding a job leaves it
+eligible for retry after lease expiry, subject to the job retry limit. Failed
+jobs retain a sanitized error for diagnostics; completed history expires after
+the existing retention window.
+
+Doctor, the dashboard maintenance endpoint, and JSON status show lifecycle
+summary and failed jobs, plus claim review counts, workspace proposal counts,
+and failed workflow runs. The Workset itself remains small: it reports only the
+resulting safety state, not the internal job log.

package/docs/1.2.0-EVALUATION-HARNESS.md

@@ -0,0 +1,51 @@
+# Memorix 1.2 Evaluation Harness
+
+The 1.2 evaluation harness prevents product claims from drifting away from
+observable retrieval behavior. It evaluates a normalized task Workset using
+deterministic requirements, not an LLM judge.
+
+## What It Checks
+
+For each task fixture, every compared Workset is checked for:
+
+1. required start files;
+2. required evidence identifiers;
+3. required cautions for unsafe or incomplete state;
+4. a strict token ceiling.
+
+The same fixture can compare a memory-only answer, the current Project Context
+answer, and a future 1.2 candidate Workset. A result only passes when it
+contains every required item and stays within budget.
+
+The initial current-context baseline is 320 tokens. The candidate-workset
+budget is 180 tokens for the same fixture, so a future implementation must
+preserve evidence and safety signals while becoming more compact.
+
+## Fixture Coverage
+
+| Fixture | Boundary being tested |
+| --- | --- |
+| typescript-auth | TypeScript source and code-bound auth decision |
+| python-worker | Python source and retry behavior |
+| go-service | Go source and health timeout |
+| docs-only | Project knowledge that has no code file |
+| dirty-worktree | Uncommitted changes must stay visible |
+| deleted-symbol | Removed source evidence must become a caution |
+| incomplete-scan | Scan limits must not be formatted as complete truth |
+
+Fixtures live under tests/fixtures/workset-evaluation/. They are intentionally
+small repositories rather than copies of the Memorix codebase, so success does
+not depend on Memorix-specific naming or history.
+
+## Running It
+
+Run the harness without network access or model credentials:
+
+~~~powershell
+npm test -- tests/evaluation/workset-evaluation.test.ts tests/evaluation/current-context-baseline.test.ts tests/evaluation/fixture-corpus.test.ts
+~~~
+
+The current-context baseline test runs the existing Auto Context path against
+real local fixture repositories. Future phases must add their real Workset
+adapter to this harness before claiming retrieval, wiki, workflow, or provider
+quality improvements.