Memory / Second Brain

Core contracts: Plugin system and capability services. Core naming guidance: Branding.

Status: design in progress. The code-module decisions below are agreed; broader memory features and implementation details remain open. The template exists in plugins/memory; Milestone 1 code and CLI integration are implemented. Verification results and remaining limitations are recorded under that milestone.

Current decision — Query-only agent interface

This decision supersedes historical AI parsing, hook-control, and plain-row CRUD exposure described below. Source code and implementation-local Markdown are the authoritative knowledge. SQLite contains derived indexes, not agent-written notes. Agents use Memory only to discover and inspect existing committed snapshots. Routine changes, such as a navigation shortcut, do not require a new documentation entry or a post-task memory summary. Document durable behavior, contracts, and non-obvious decisions in the nearest owning README/docs only when useful.

Verification: generated registration exposes eight query tools. A narrowly scoped check accepted their valid inputs and rejected all eight retired tool names through the schema, natural-language parser, and execution boundary. App definitions retain parse and hook maintenance while excluding row commands. Targeted ESLint passed; scoped TypeScript checked 33 Memory files with zero diagnostics. Actual CLI shared search returned code and Markdown hits from existing snapshots, with freshness and pagination. The running host and its materialized skills require a user restart; authenticated app verification remains pending. No index rebuild or data migration is needed to use the revised queries.

Universal search integration

Memory participates in the core universal-search contract without taking over search of other apps' databases. search-provider.ts adapts existing shared discovery across workspace-contained indexed projects and opens matched code and Markdown files in the timeline via workspace-file-view:v1 (with fallback to the inspection services when no file location exists). Queries remain read-only; no parsing or hook installation occurs. See the user guide.

Verification: core and web TypeScript pass; the integration files pass ESLint. A read-only check against the existing database validated schema-checked search, pagination, address encoding and first-hit inspection via a fresh capability registry. No index/data writes or authenticated browser verification were performed.

Compiler context follow-up — Landing ambient declarations

The landing tsconfig selects web sources outside its project directory. Filtering compiler roots by index eligibility dropped standalone ambient declarations for demo flags and window.webln, producing TS2367/TS2339 in imported web components. Compiler context and graph ownership must be separate: project-local Git-eligible sources and committed external .d.ts tsconfig roots participate in compilation without pulling in unimported external .ts/.tsx files or sibling repositories from inherited parent tsconfig.json includes; only project-local Git-eligible sources are indexed. External .d.ts roots and imported dependencies remain snapshot/cleanliness/manifest inputs.

Verification: a non-publishing compiler check using the committed snapshot host retained 635 compiler roots and reported zero compiler diagnostics. Both web declaration files were present in the program and provenance manifest but excluded from index eligibility; all 20 index-eligible program files stayed inside landing. The version-5 manifest rejects an analyzer-4 cache. Targeted ESLint and tsc --noEmit --project plugins/memory/tsconfig.json passed. No stored index was published and no restart signal was touched.

Original motivation (historical)

AppWeaver knowledge is scattered: workspace code, markdown docs, app DBs (todo, bookmarks, journal, jobs), core DB (dm-bot.sqlite: state, sessions, session_messages), and later pdf/docx. Agents re-discover the same context every run. A local second brain gives one place to ask "what do we know about X?" with citations back to the source.

If we had it:

Settled

  1. Push, not pull. Supplier calls memory right after its own commit via bun src/cli.ts memory <tool> '<json>'. Memory owns how to upsert. Example: todo app adds item, then calls memory update-graph with the new triplet.
  2. Explicit supplier identity. Payload carries sourceId + kind (app-db, md-chunk, core-db...). No core-derived caller magic, no provider-registry lookup in v1.
  3. Git sync is commit-only, per-repo. Automatic indexing is opt-in for each project. Its post-commit hook invokes shared parse; the command owns initial indexing, change detection, and rebuilding. Compare against the last successfully indexed baseline, not just HEAD~1, so missed runs can catch up. No dirty/untracked source indexing in v1.
  4. Query is memory plugin ai.ts tools with zod schemas, callable via src/cli.ts like file bottomup.summary. The first code module exposes code.parse, code.search, code.inspect, and code.expand. General search now combines code and Markdown indexes; general ask and supplier ingestion remain later features.
  5. Triplet model. Subject --relation--> Object, e.g. prepare presentation#123 --child-of--> tomorrow's meeting#122. Exact relations from apps (parent/child, tags, links) need no LLM.

Open / deferred

Code query scope (settled)

Code module design (settled)

Purpose and first targets

Build a deterministic structural map that helps agents locate declarations, references, callers, and dependencies before reading implementations. Start with NR (plugins/nr), then apply the same workflow to AppWeaver itself. The graph supports discovery, not a substitute for understanding source behavior.

Workspace and project selection

Parser and dependencies

Use the TypeScript compiler API with cross-file resolution from the start: AST traversal plus a project Program and type checker. Honor compiler options and import aliases instead of guessing resolution from import strings.

Packages found in the root installation during design research:

Package Version Assessment
typescript 5.9.3 Selected: native TS/TSX AST and semantic analysis
@typescript-eslint/typescript-estree 8.67.0 Alternative for ESTree output
@typescript-eslint/parser 8.67.0 ESLint-oriented wrapper; unnecessary here
espree 10.4.0 JavaScript/JSX parser, not TypeScript syntax

Declare typescript as a Memory runtime dependency. A compatible root-installed copy may be shared through normal package resolution, but transitive development dependencies alone are not a runtime availability guarantee. Keep the analyzer under plugins/memory; core supplies workspace services and generic contracts. No external API, embedding service, or database server is needed.

Stored metadata and graph

Use plugin-local SQLite through bun:sqlite, separating projects and workspaces by identity in the same database. Store derived compact metadata:

Do not persist the full AST or full implementation bodies for this module. Metadata is generated during parsing, not reparsed on every query, and updated atomically with relationships. Source code remains authoritative.

Candidate node kinds include files, functions, classes, methods, interfaces, type aliases, and significant variables/properties. Candidate relations include declares, imports, exports, reexports, extends, implements, references, calls, and typed-as. Exact extraction coverage and identity rules still need specification. Never invent a target for dynamic expressions.

Parsing, idempotency, and errors

Tools

Queries use Zod-typed arguments through plugin ai.ts and src/cli.ts. Parsing is an explicit app maintenance command:

/memory code.parse --project plugins/nr --fresh
Tool Behavior
code.parse Analyze one whole project and immediately save its index
code.search Search names, signatures, and documentation; prioritize exact name matches
code.inspect Return compact symbol metadata, location, and direct relationships
code.expand Traverse incoming/outgoing relationships, capped at three hops

The three query tools are read-only and require one specified project. Search results indicate matching fields. No body-return option is planned. Queries describe the last successful indexed snapshot and report freshness and coverage, including external-reference boundaries.

Remaining code-module details

Current sketch

Suppliers (todo, file hook, core adapter) push { sourceId, chunks, triples }. Memory stores nodes, edges, nodes_fts in its own SQLite, traverses with WITH RECURSIVE ... depth <= 3.

Earlier illustrative proposal for docs/BRANDING.md (Markdown choices are superseded by the agreed design below):

Implementation checklist

This supersedes the earlier P0–P5 sketch. Unchecked items are unimplemented or unverified; the existing scaffold is a starting point, not a completed milestone.

Milestone 1 — Manual indexing and queries for NR

Investigation findings

These are static-inspection findings, not a successful compiler/indexing run:

  1. Memory scaffold draft removal. plugins/memory/db.ts opens plugins/memory/db.sqlite with foreign keys and WAL. Draft/review commands and draft table creation were removed so remaining CRUD operations apply immediately. Existing scaffold data and namespaced code-index tables are preserved; the dormant empty memory_drafts table is not dropped automatically.
  2. CLI registration needs modernization. plugins/memory/ai.ts exports ToolCallSchema/executeTool, but no aiDefinition. Both src/cli.ts and scripts/generate-tools.ts require that object; generation requires its toolCallSchema to be a Zod discriminated union. plugins/nr/ai.ts is a current example. MemoryPlugin also needs its aiDefinition attached for registered in-process tool invocation.
  3. The template uses obsolete agent types. Memory's init.ts reads context.runAgent, while current PluginInvocationContext exposes agent. Its adapter types import RunAgentFn, which is absent from the current core plugin contract. Adapt the old natural-language handler to PluginAgentService without introducing a second agent runtime or changing its draft semantics.
  4. Workspace service exists, but not in AI tool props. PluginContext.workspace provides getActiveTarget/rootFor; AiExecuteToolProps has no workspace field. CLI imports ai.ts directly and does not initialize MemoryPluginContext. Do not depend on that module global or copy File's direct core-DB workspace lookup. The implemented approach now uses the generic core helper src/core/workspace.ts::resolveActiveWorkspaceRoot for standalone tools; app commands use PluginContext.workspace directly. No AI-tool props change or Memory-specific core routing was necessary.
  5. NR inherits a workspace-wide configuration. Its root tsconfig.json only extends ../../tsconfig.json. Inherited include patterns refer to AppWeaver's src, scripts, plugins, and generated directories. Parsing that config unchanged as a root-file list would select far more than NR. Keep TypeScript's effective options and correctly based aliases, but intersect index root files with the requested project boundary and Git eligibility.
  6. Git boundaries are useful here. NR's .gitignore excludes SQLite files; AppWeaver's excludes plugins/ and most generated/ content. Evaluate rules in the owning repository: parent plugins/ exclusion must not exclude NR when NR is the explicitly selected project. Imported ignored/generated files may still be required for resolution, with evidence/provenance but no full indexing.
  7. Baseline status: NR had a clean working tree at commit 4f1965457d9e1d3a1f339c6e5c6f4e0b2b60d53c. Memory's scaffold files were untracked, and root docs/MEMORY.md was untracked. These observations do not authorize committing them. Generated plugin registration was empty during inspection; validate installed-plugin selection before regenerating tooling.
  8. No compiler-readiness claim yet. NR imports core code, so strict diagnostic policy can block its first index on errors in the dependency closure. Do not silently relax that policy or repair unrelated code without investigating the actual diagnostics. No tests, compilation, or Memory DB mutation ran during this investigation.

Technical implementation plan

The following is the technical plan and its reconciled implementation notes. The service is implemented; verification and remaining limits are listed below.

A. Separate transport from the deterministic code service.

Proposed plugin layout:

plugins/memory/
  code/
    schemas.ts       # Zod inputs/results, node/relation vocabulary
    project.ts       # core workspace -> canonical project/repository
    git.ts           # committed trees, ignore selection, dirty inputs
    snapshot.ts      # compiler host and input provenance/fingerprints
    analyzer.ts      # TypeScript Program, diagnostics, extraction
    identity.ts      # deterministic declaration/reference identities
    store.ts         # schema migrations and atomic snapshot publication
    queries.ts       # search/inspect/bounded traversal
    service.ts       # parse lifecycle shared by all entrypoints
  commands/code-parse/{definition,adapter}.ts
  commands/code-search/{definition,adapter}.ts
  commands/code-inspect/{definition,adapter}.ts
  commands/code-expand/{definition,adapter}.ts
  commands/ai/{schemas,execute-tool,agent-instructions}.ts

Command adapters and aiDefinition.executeTool call the same service. The code analyzer never imports or executes target project modules and never calls an LLM. Add typescript to Memory's runtime dependencies, using the compatible existing root installation; do not add a graph database package or ignore-pattern package.

B. Supply workspace context generically.

Implemented src/core/workspace.ts::resolveActiveWorkspaceRoot, using core's existing workspace state and canonical AppWeaver/parent paths. Standalone tools call it directly; app adapters use their stored core workspace service. This supersedes the earlier proposed AiExecuteToolProps extension. Core can already invoke registered Memory tools in-process without model inference. No direct core import from plugins/memory or Memory-specific CLI branch was added. Capture workspace root/target once, canonicalize project paths with realpath, and reject project paths outside the authorized workspace, including symlink escapes. Pass the captured root to services, not a global current-directory guess.

C. Capture a reproducible Git/TypeScript snapshot.

  1. Resolve project to an existing directory with root tsconfig.json, owning Git repository, and a committed revision. Refuse a repository without commits.
  2. Use Git's NUL-delimited status/tree/file commands and argument arrays, not shell interpolation or a hand-written ignore matcher. Select committed TS/TSX files in the project, with nested repository boundaries and test labels. Untracked non-ignored TS/TSX and changed project source/configuration trigger the agreed commit-first failure. Indexed content comes from Git blobs, not current files.
  3. Load committed tsconfig and its extends chain through TypeScript's config APIs. Preserve option path bases, project-local eligible compiler roots, and committed .d.ts ambient roots outside the project (analyzer 6 scopes external tsconfig roots to .d.ts declarations and keeps gitignored sibling directories out of config directory traversal). Config-selected local files and imported local declarations form the proposed index closure when Git-eligible and inside the project; outside files are resolution inputs/minimal references only. Document this distinction in coverage.
  4. Implement a custom CompilerHost/config filesystem view. Workspace-owned dependency source and config reads use captured revisions of their owning repos, with blob caching; installed package declarations and compiler libraries are local environment inputs whose hashes/version are recorded. Do not mix Git source reads with working-tree module discovery: existence, directory listings, and resolution metadata must use the snapshot view too.
  5. Record every consumed source, configuration, and module-resolution input, including package metadata, lockfiles relevant to the environment, ignore/file selection inputs, and analyzer/compiler version. Verify dirty consumed external inputs and recheck captured revisions before publication; fail rather than silently indexing inconsistent inputs. Do not block on unrelated dirty docs.
  6. Unchanged checks validate the previous input manifest and current file inventory, including resolution-affecting additions/deletions. If validity is uncertain, re-analyze the whole project. fresh always bypasses this optimization.

The snapshot host is the main complexity risk: NR's inherited config and imports cross Git repositories. Implement it explicitly rather than label live compiler output as committed content. Project references/multiple configs require either explicit support or a diagnostic in Milestone 1, not silent partial indexing.

D. Extract supported facts with explicit evidence.

Build one ts.Program over selected roots and dependencies with no emit. Collect config/options/global diagnostics and syntax/semantic diagnostics for the relevant closure, respecting configured compiler checks such as skipLibCheck. Any error blocks publication; warnings and dynamic-target limitations remain distinguishable.

Use two passes: declaration metadata/identities, then relationship extraction. Resolve aliases with the type checker; associate references and calls with their lexical owners and resolved declarations. Preserve overload declaration locations under a common symbol where appropriate; merged symbols can have multiple source locations. Proposed initial relations are declares, imports, exports, reexports, extends, implements, references, calls, and explicit typed-as. Report unsupported/dynamic forms without speculative edges.

Identity keys combine canonical project identity, relative file, declaration kind, and lexical qualified name, with a deterministic disambiguator where needed. Avoid line-number-only identities. Anonymous nodes may use structural positions and can change identity on edits; expose that limitation. External targets stay project-local reference nodes, even if another project's index already exists. Capture signatures and attached documentation without serializing initializer or function bodies. Bound generated inferred types to avoid huge signatures and record truncation when needed.

E. Persist one replaceable snapshot per project.

Implemented namespaced tables: memory_code_schema, memory_code_projects, memory_code_nodes, memory_code_edges, and memory_code_fts. Compact typed locations/evidence are stored as JSON on nodes/edges, and input provenance and negative lookup records as a project manifest, rather than introducing separate tables for each field. Search is project-filtered FTS5 over names, signatures, and documentation. Use schema-versioned migrations; project-scoped unique constraints prevent duplicate facts, and evidence has file and source-range ownership. Logical edges deduplicate separately from call/reference occurrences. Store analysis status/provenance, not full ASTs or bodies.

Analyze outside the write transaction. In a short BEGIN IMMEDIATE transaction, check the previously observed project generation, replace only that project's derived tables and FTS entries, and advance its input manifest/revision/generation. Foreign-key cleanup removes obsolete evidence/facts. On error, rollback and retain the old successful snapshot. If another run published first, reject the stale run instead of overwriting it. WAL allows queries to read the old snapshot during work.

F. Define bounded, project-scoped tools.

Proposed arguments, to be encoded as explicit Zod schemas:

Tool Arguments
code.parse project, fresh
code.search project, query, nullable kind/file filters, test filter, bounded limit/cursor
code.inspect project, node ID, bounded relationship limit/cursor
code.expand project, node ID, direction, relation filters, depth 1–3, node/edge budgets

Search combines exact name priority, normalized identifier matching (including camelCase/underscore segments), and escaped FTS text queries. Return match fields and stable tie-breaking. Inspection returns metadata and direct edges/evidence; expansion uses visited-node deduplication and budgets in addition to depth, with explicit truncation. Use one SQLite read snapshot per query. No arbitrary SQL, cross-project graph traversal, or source-body option.

Every success result is validated by its output schema. Code tools render compact text by default or full JSON with format: "json", through the existing string-returning CLI contract. Include indexed revision, coverage/external boundaries, and freshness. Cheap checks can report HEAD drift; do not claim dependency freshness without manifest validation (use unknown when not checked). Failed parsing must yield diagnostics and a nonzero CLI exit, not only a success-exit error string. The CLI's current catch/exit path can carry a structured diagnostic error message; align app command handling with the same service result without adding a Memory-specific CLI branch.

G. Integrate and verify in small increments.

Modernize the scaffold's agent/AI contracts first; add typed schemas/service and SQLite migrations; build snapshot selection and compiler analysis; then wire the four tools, command help, and generated skill/CLI registration. Preserve existing draft CRUD data/behavior unless a separate removal is agreed. Inspect generation diffs so unrelated plugins/skills are not silently dropped or enabled.

Run targeted ESLint with --fix for plugin changes and appropriate broader lint for shared core type changes. NR's first actual parse is an explicit DB-mutating verification step; record returned diagnostics and counts when that execution is requested. Do not check off NR exit criteria based on static inspection, and do not add/run tests without user request. No browser verification is needed here. Backend/core changes require a deliberate host restart before app testing; never touch restart.requested from the active AppWeaver chat.

Readiness and next implementation step

Implemented service layout is code/{schemas,project,snapshot,analyzer,store, queries,service}.ts, with identity logic inside the analyzer and shared code command definitions in commands/code/definition.ts. The draft/review commands and tables were removed, and remaining CRUD operations execute directly against SQLite. Memory's scaffold was modernized locally; the template generator was updated to make draft scaffolding optional.

Current limits: project identity is its canonical root path; project moves and multiple referenced tsconfigs need later work. Snapshot file matching uses TypeScript's runtime matchFiles export, guarded at runtime, with the installed 5.9.3 compiler. Workspace-owned committed files use Git blobs; ignored generated dependencies and installed package declarations are explicitly hashed auxiliary inputs. Queries report dependency freshness as unknown rather than re-running analysis. Callbacks/computed/anonymous targets without a supported declaration are limitations, not invented call edges. Evidence is capped at 20 locations with counts/truncation; signatures at 2,000 characters each (up to 10), docs at 4,000.

Compact output refinement

Agreed after comparing verbose search JSON: all four code tools accept format: "text" | "json", defaulting to text, with the equivalent --format app-command option. Typed result schemas and the stored index remain the common source for both renderings; no reindex is required for presentation changes.

Generated agent skill

The durable skill source is plugins/memory/ai.ts (agentInstructions, skillNotes, skillRules, and aiDefinition). bun run plugin:generate produces .appweaver/skills/appweaver-memory/SKILL.md; do not edit that generated file.

Guidance now specifies project selection, search -> inspect -> bounded expansion -> source reading, external navigation, missing/stale indexes, full IDs, pagination, and indexing diagnostics. The text/JSON decision table recommends text for discovery and JSON for scripts/full stored metadata, with the measured NR comparison and an explicit note that byte reduction is not a token measurement. Plain-row CRUD is distinguished from the code graph tools.

Real task: NR Timeline Authors

Other observations: literal treeItem usage is not itself a declaration search hit, and broad timeline searches include many property matches. Exact file/kind filters and inspecting a file declaration helped narrow the task. File-plugin JSON bottom-up summaries were missing for this subtree, so they did not supply additional context. This is qualitative evidence of discovery usefulness, not a measured token/time comparison. The index still describes the committed baseline; the new feature must be committed before it can be indexed.

Milestone 1 verification record

Call-target coverage follow-up

The NR snapshot's 16 unresolved calls were reviewed: nine invoked functions returned by transaction wrappers, two direct inline-function invocations, and five injected callbacks. The transaction method and body calls were already represented; the wrapper-result invocation lacked a concrete target. Inline functions are statically identifiable; callback implementations require separate data-flow work.

The persistent index is in plugins/memory/db.sqlite. CLI verification is usable immediately; loading the updated plugin/helper in the running app needs a host restart.

Exit criteria: a clean committed NR project can be indexed and queried with accurate locations and scoped relationships; failures do not replace its index; repeated runs do not duplicate facts. No full source bodies are returned.

Milestone 2 — AppWeaver as a separate project

Exit criteria: NR and AppWeaver coexist in the database and can be queried independently without duplicate ownership or accidental cross-project traversal.

Milestone 3 — Settings and opt-in automation

Exit criteria: enabled projects index after commits using the manual command's same rules; disabled projects retain manual operation.

plugins/memory/code/hooks.ts implements explicit opt-in tooling; indexing alone never installs hooks. Preview/status are read-only. Install records prior local Git configuration and creates .git/appweaver-memory-hooks (or the corresponding Git metadata directory), then sets only local core.hooksPath. Shared/global hook files are never edited. Standard hook names delegate to their original paths; post-commit invokes existing work before the fixed, shell-quoted Bun runner. Nested release amendments skip duplicate Memory runs but preserve original hooks.

hook-runner.ts clears Git-local environment for dependency repository queries, locks concurrent runs, invokes the same parser with the explicit project/workspace, and records the attempted revision/result. Failed analysis preserves the index and Git commit; missed/busy runs catch up through manual parsing or subsequent commits. Removal restores the previous local setting and validates managed-file ownership; edited/redirected hooks, unsupported worktree config and active runs are surfaced. CLI text and JSON expose automation status and last run. Natural-language Memory AI cannot install/remove hooks; agents must have an explicit per-project user request.

No automation is being enabled on the user's existing projects by implementing this feature. Broader settings UI and full real release-commit lifecycle verification remain separate work. Unsupported project/Git metadata/worktree cases are documented in the plugin README.

Indexed-projects widget

code/projects.ts lists stored indexes within the current canonical workspace; it does not walk for unindexed projects or trigger indexing/hook installation. The widget uses generic WebNodes and scoped CSS entirely inside the Memory app. Each expandable row exposes short index/HEAD revisions (full values on hover and in JSON), browser-local timestamps, counts, uncommitted-input status, hook state, last-run details, and stored diagnostics. Missing directories stay visible with disabled actions; symlink escapes are hidden.

The projects AI/CLI tool returns text or JSON. App commands render the widget by default. projects.hook --project ... renders a preview modal with the exact command/delegation and explicitly labeled Enable/Disable actions. These reuse code.hook; changed/unverifiable configurations are not overwritten. Reindex uses fresh: true to publish a snapshot at the current HEAD even if relevant inputs would otherwise be unchanged. Reindex and hook changes refresh the origin widget.

Timeline presentation follow-up: removed the projects header/singleton registration so /memory projects produces a regular timeline card rather than a docked widget. Reindex runs through the timeline action/refresh path; hook preview remains a modal with origin-card refresh. Hash display uses eight characters without shortening the underlying values used for HEAD comparison. A reusable generic timestamp WebNode displays epoch milliseconds in browser-local time, keeping Memory-specific logic inside the plugin. Indexed-at and automatic-run times use this primitive; CLI text uses process-local time and JSON retains raw timestamps/full hashes.

Actionable indexing outcomes

code/attempts.ts stores one latest attempt per project in an additive SQLite table. IDs advance on each start, so old concurrent completions cannot update a newer row. The shared parse service captures failures before rendering errors; successful snapshot metadata and its limitation diagnostics remain independent. Failed attempts are visible even when project rows are collapsed and persist after Refresh. Complete failure details expand separately from successful-index limitations.

The NR analyzer-4 rebuild succeeded with 14 expected limitations: nine calls to returned transaction functions and five injected callback invocations. These describe graph coverage and do not make an indexing attempt fail. They remain separate from errors belonging to a failed attempt. Past failures predating attempt tracking are not fabricated from successful-index diagnostics.

Markdown and shared discovery — Agreed design and implementation

The design Q&A is settled and implementation is authorized. Index committed .md and .markdown anywhere in a project, including feature-local READMEs. Projects share identities across indexes; TypeScript requires package.json + tsconfig.json, while Markdown supports the default workspace without those files. More-specific projects own their files; nested repositories never belong to the parent snapshot.

Every heading creates a section containing its direct text, with parent/child relationships and an introductory section. Long sections have block-oriented search chunks with exact source ranges; links target sections, not chunks. Standard inline, reference-style and same-document links use GitHub heading anchors. Explicit links between projects retain both identities/revisions; unavailable/missing targets remain visible. Queries never automatically broaden their selected-project scope.

Use local weighted FTS5 over title/heading/tags/body, retaining original Markdown. YAML frontmatter supplies title/tags; other fields and raw metadata are preserved. Malformed metadata warns without hiding the body. Vector search, wikilinks, inferred knowledge, and documentation-to-code target resolution are deferred.

markdown.parse/search/inspect/expand mirror specialized code tools. Shared parse attempts applicable indexes independently and shared search combines bounded ranked results with kind/project/revision/inspection IDs. A documentation-only project skips code as not applicable. Commit hooks use shared parsing. Dirty relevant inputs reject only their index; atomic generation-checked publication preserves the last successful snapshot. Markdown parsing reuses unchanged blobs/parser versions, removes deleted facts, and refreshes link resolution as targets change. Latest-only snapshots retain provenance. One widget row contains separate code/Markdown outcomes and reindex actions.

Implementation uses plugin-local markdown/{schemas,parser,snapshot,store,queries, service}.ts, discovery.ts, and Markdown/shared command definitions. CommonMark/GFM and GitHub slugging use dedicated AST/slug libraries; YAML is parsed without custom executable tags. Runtime dependencies and the plugin lockfile are declared locally. The existing hook wrapper/config format is unchanged; its runner now orchestrates independent indexes, so installed wrappers continue to validate without reinstallation.

Verification: targeted ESLint passed and scoped TypeScript reported 51 files with zero diagnostics. In-memory checks parsed actual committed Journal (three documents) and File (two documents), then returned unchanged with reuse. NR correctly rejected dirty docs/DB_REFACTOR_PLAN.md; Job rejected dirty package ownership configuration. Virtual-source/in-memory publication checks covered malformed frontmatter, reference links, duplicate/nested headings, fenced examples, chunk/text budgets, cross-project links and incoming backlink metadata without content traversal, target heading changes, deletion, generation conflicts and rollback preservation. Shared parsing published Markdown despite code failure. Joint searches over copied existing code data and committed Markdown verified both result kinds and cursor continuity. Generic WebNode validation checked combined widget status/errors/actions; app flag parsing checked repeated exclusions/relations. Actual shared CLI search reported available code and missing Markdown separately, with usable IDs and continuation. Existing successful production indexes were not reindexed by these checks; openDb applied additive tables.

Link resolution is derived at query time from one SQLite read snapshot rather than stored as stale cross-project foreign keys. Parsed source references retain absolute destinations and evidence; latest indexed targets supply resolution/backlinks and source/target revision provenance. Shared search ranks per-index ordinals and advances only consumed backend offsets. Markdown inspection is paginated, defaults to 12,000 characters, and retains one logical section even when chunked. Section IDs are project/path/slug based; renames and duplicate-heading reordering may change them. Git-root documentation-only projects are supported in addition to configured roots and workspace fallback. Source files above two million characters require exclusion or splitting. Real authenticated UI and release-hook execution remain user verification; no automated tests were added/run and restart.requested was not touched.

Later milestones — Design still open

Next work queue after agent guidance

Recommended order; this is planning, not authorization to execute every item:

  1. Close Milestone 1 verification gaps. Exercise an actual committed-source edit/deletion, blocking compiler error, and recovery without losing the previous index. Verify authenticated app commands with a user-provided context after restart. These are outstanding checks, not a new parser feature.
  2. Milestone 2: apply the service to AppWeaver. Index the clean committed root as a separate project, check alias/type-only references, project isolation, effective tsconfig TSX coverage, and resource usage. Harden the analyzer only against issues actually found. Respect current commit-first guards; do not automatically commit the existing work to make indexing possible.
  3. Milestone 3: project status/settings. The indexed-projects widget and read-only projects tool are implemented with counts, index/HEAD freshness, diagnostics, last-run status, and explicit hook controls. Verify the widget in the authenticated UI; next agree unindexed-project discovery and broader settings.
  4. Milestone 3: post-commit automation. Integrate the opt-in hook with existing release hooks, invoke the same parser using explicit project/revision context, and report failed/missed runs without undoing Git commits.
  5. Broader Memory ingestion. Design reusable supplier/consumer contracts and reliable change delivery, then choose Markdown/bottom-up retrieval/extraction rules. App/core DB suppliers, PDF/DOCX, and general answering remain later work. Vectors and automatic cross-project traversal remain research/design items.