Imported from JasonZhu314/Exocore (AGENTS.md). Install upstream with npx skills add JasonZhu314/Exocore. Copyright stays with the author.

AGENTS.md

This file provides guidance to Codex agents working in this repository.

Project Identity

This repo builds Exocore, the local kernel for Project Exocortex.

Exocore is a local-first control plane for AI agents. It gives agentic tools a user-owned substrate for:

• source-linked memory;
• staged memory promotion;
• memory governance;
• privacy-aware local/cloud/human-confirm routing;
• prompt and output transformation;
• auditable deletion;
• personalization evals;
• later E2P ranker or adapter experiments.

The repo should build the substrate that agents call for memory, routing, transformation, governance, provenance, deletion, and evaluation.

North Star

The long-term vision is an operational digital twin of a human user: a local, continuously evolving model that develops tacit understanding of the user's preferences, working style, research taste, habits, constraints, and decision patterns through long-term interaction.

The engineering path is explicit first, learned later:

raw interactions
  -> governed explicit memory
  -> profile and preference structure
  -> evals and failure cases
  -> E2P candidate data
  -> rankers / adapters / learned priors
  -> operational digital twin behavior

Do not confuse the MVP with the destination. Explicit memory is the evidence ledger, audit substrate, and dataset factory. Learned personalization is allowed only after the explicit substrate can govern it.

Scope

In scope now:

• local SQLite-backed store;
• raw episodes;
• staged memory candidates;
• canonical source-linked memory;
• profile rules;
• governance decisions;
• privacy labels;
• local/cloud/human-confirm routing;
• prompt transformation;
• output transformation;
• deletion lineage;
• eval harness;
• CLI;
• local HTTP API;
• optional MCP integration.

Out of scope for the first implementation wave:

• LoRA training;
• TTT;
• autonomous profile editing;
• vector DB dependency;
• cloud sync;
• desktop UI;
• full assistant behavior;
• companion UX;
• consciousness or digital-self claims.

Adapters, rankers, and local model fine-tuning are future E2P work. Do not start them before retrieval-only Exocore has measurable failures and deletion/governance tests pass.

Current Source Of Truth

The high-level project note lives in the Obsidian research vault. This repository is the authority for code, tests, configs, and implementation docs.

When planning implementation:

1. Read this file.
2. If LOCAL_CONTEXT.md exists, read it for local private context. It is gitignored.
3. Read README.md, ROADMAP.md, and docs/AGENT_WORKPACKAGES.md.
4. Inspect repo state with git status --short --branch.
5. Identify the current milestone.
6. Implement only the next small, testable step.

If code and docs disagree after implementation begins, trust working code and focused tests first, then update docs as part of the same task when practical.

Engineering Taste

This project should be mechanism-first, not demo-first.

For nontrivial design or eval work, use this loop:

1. Question: what mechanism are we testing or implementing?
2. Hypothesis: what should happen if the design is correct?
3. Diagnostic: what test, metric, trace, or fixture distinguishes success from alternatives?
4. Result: what did the implementation or test show?
5. Interpretation: what is supported, what is not, and what remains ambiguous?
6. Next step: what is the smallest useful follow-up?

Prefer simple, inspectable code over clever abstraction. Keep dependencies boring until the kernel works.

Architectural Invariants

• Every canonical memory must point to evidence.
• Uncertain claims stay staged.
• Every memory write must have an authorized source.
• Cross-domain memory use must be explicit and auditable.
• Sensitive memories default to never_train.
• Sensitive memories default to stricter read permissions.
• Router decisions must be logged and explainable.
• Local-only data must never be sent to cloud providers.
• Deletion must cascade through candidates, canonical memories, embeddings, eval examples, and trainable datasets.
• Factual memory stays explicit. Learned artifacts may encode stable behavior, style, taste, or routing priors only after E2P.
• Adapters or rankers cannot be promoted without eval improvement and rollback metadata.

Implementation Principles

• Start narrow and offline.
• Build the explicit governed kernel before product polish.
• Use SQLite and ordinary tables first; FTS is acceptable early.
• Do not add a vector DB as a founding dependency.
• Keep schemas explicit rather than burying state in untyped JSON blobs.
• Keep CLI commands deterministic and scriptable.
• Make route, transform, governance, and deletion decisions traceable.
• Treat documentation as part of implementation.
• For nontrivial paths, use clear names, small functions, and concise comments that explain why, not what.

First Milestone

The first milestone is an offline kernel:

1. package scaffold;
2. SQLite store;
3. raw episode schema;
4. staged memory candidate schema;
5. canonical memory schema;
6. governance decision schema;
7. deletion lineage;
8. source-linked retrieval;
9. minimal eval runner;
10. CLI commands.

Stop condition:

A synthetic session can be captured, converted into staged candidates, promoted into source-linked memory, retrieved, audited, deleted, and verified as deleted by tests.

Commands

Do not invent commands in final reports. If a command is not configured yet, say so.

What To Ask The Human Before Major Changes

Ask before:

• changing the project scope;
• adding heavy dependencies;
• adding a vector database;
• adding cloud provider integration;
• adding local model inference requirements;
• starting adapter, LoRA, or TTT work;
• changing the memory governance model;
• changing deletion semantics;
• building a UI;
• committing work that is not a coherent milestone;
• pushing changes.

Version Control And Handoffs

• Inspect git status --short --branch before starting and before reporting back.
• Keep commits focused on coherent milestones.
• Do not commit local databases, raw runs, private context, or heavy generated artifacts.
• Never rewrite, reset, or discard user changes unless explicitly asked.
• Stage files deliberately.
• Commit only when asked, at a clear milestone, or before a handoff when the work is ready.

After a milestone or handoff, report:

• what changed;
• what was tested or not tested;
• the commit hash if a commit was made;
• known caveats;
• a compact summary for the next Codex session.

Agent Ownership

Before parallel Codex agents start work, read docs/AGENT_WORKPACKAGES.md.

Agents should own disjoint write scopes. Do not edit another active agent's module unless the user asks or the shared contract requires it. If a shared schema must change, update the relevant docs and tests in the same task.

Reporting Back To The Research Vault

When implementation changes affect the Exocortex research direction, summarize the result in the external research vault rather than leaving it only in code comments or raw logs.

Record:

• the question tested;
• the implementation or eval used;
• the result;
• what changed in the project plan;
• unresolved questions.