memdsl

# memdsl

<!-- mcp-name: io.github.Liyuan1992/memdsl -->

[English](#english) | [中文](#中文)

## English

**Agent memory as source code the agent reads itself.**

### 0.9 release line with experimental Edges

Version 0.9.0 adds an opt-in `memdsl.workspace.v3` first-class explicit Edge
experiment. It does not rewrite the frozen 0.8 contract: legacy relations and
authority remain compatible, explicit Edge proposals always require a human,
and explicit `supersedes` is graph-only. Source remains runtime authority;
review/audit is a workflow contract, not a non-bypassable grant ledger. See
[the Phase 6 design and risk matrix](docs/DESIGN_explicit_edges_phase6.md) and
[the release-scope evidence freeze](docs/RELEASE_SCOPE_PHASE6.md).

### Stable 0.8 compatibility contract

The 0.8 contract combines the previously unpublished navigation and View work
now shipped by 0.9.0; neither 0.7.0 nor 0.8.0 was released separately. Stable
public contracts include the v1 compatibility/authority surfaces, Catalog v1,
Trace v1, indexed
query/search trace, report diagnostics, public rebuildable `CompiledWorkspace`
/ `compile_workspace`, `memdsl.workspace.v2`, exact `use`, the generic
`dialect_mapping` capability, `ViewContext`/`ResolvedView`, and the explicit
opt-in v2 read schemas. Map v1 remains supported throughout the 0.8 line and
will not be reconsidered for removal before 1.0.

The software release is `0.9.2`, anchored by tag `v0.9.2`. It adds official
MCP Registry metadata and a UV-based MCPB installer for the default-read-only
`memdsl-mcp` server. Parser, schema, review, query, authority, and MCP tool
contracts are unchanged from 0.9.1. Neither patch nor package-level release
promotes the opt-in Edge surface to stable or makes automatic Edge generation
authoritative.

The real-world rollout quality of `quarantine`/`strict`, dialect-candidate
learning, and host-attested principal integration is still experimental and
opt-in. Their safety invariants are not experimental: authorization happens
before aggregation, incomplete hard-rule evaluation never becomes ALLOW,
non-authoritative edges never gain authority, and repair paths remain open.
`CompiledWorkspace` is a public rebuildable handle; its cache/index layout,
compiler contract strings, and synthetic timing constants remain implementation
details. Workspace-v3 first-class Edges are experimental. Automatic dialect
learning, automatic Edge candidates, inferred authority, and cold-history/
incremental compilation are not shipped. Host extraction/sanitization and
private schemas/policies/samples remain outside memdsl and are not release
gates.

memdsl started with a retrieval failure. A memory system built on RAG failed
to recall a memory it certainly had; a coding agent pointed at the same raw
memory files traced it down in a few steps. Same model — the difference was
the context contract. The agent knew the memory existed and could keep
reading toward it; the retriever got exactly one similarity guess, and a
miss looked identical to absence.

memdsl turns that difference into the product. Long-term memory lives in
readable, lintable, reviewable `.mem` source files, and every runtime
surface is built for an agent that reads memory itself:

- **A bounded memory Catalog** (`memdsl catalog`, MCP `memory_catalog` /
  `memdsl://catalog`, Python `build_memory_catalog`): paged module/type/subject/
  status navigation with item and byte budgets, revision-bound cursors, and no
  duplicated structured/text representation. It is the recommended
  session-start surface for large workspaces.
- **A compatible memory map** (`memdsl map`, MCP `memory_map` /
  `memdsl://map`): the existing v1 full index remains available for older
  clients and is not silently changed into Catalog.
- **Indexed queries that explain their misses** (`search_trace` in every
  serialized pack): deterministic lexical postings preserve the v1
  EvidencePack ordering and authority lanes while exposing View/source
  identity, candidate-pool counts, filter-hidden matches, bounded vocabulary
  suggestions, and safe retry queries. Suggestions never write aliases or let
  candidate symbols redirect retrieval.
- **A bounded relation Trace** (`memdsl trace`, MCP `memory_trace`, Python
  `trace_memory`): deterministic incoming/outgoing/both BFS navigation with
  relation filters, explicit cycle/back/cross edges, hard depth/node/edge/byte
  budgets, and revision-bound cursors. Connectivity is navigation, not proof.
- **Report-only link diagnostics** (`memdsl lint`, MCP `memory_lint` and
  `memdsl://status`): duplicate ids, ambiguous/wrong-prefix/dangling targets,
  unknown relations, revision cycles, and supersede forks are explicit. Cycle
  edges cannot make every participant disappear, forks never select a winner,
  and default Map/query authority remains v1-compatible.
- **Raw source as the floor** (`memdsl://file/{file_id}`): the agent can
  always drop down and read the actual declarations, the way a coding agent
  reads code.

The failure mode that started the project now fails loud — the memory
exists, a filter hid it, and the trace says exactly that:

```console
$ memdsl query examples/domains/coding -q "force push main" \
    --type coding.bug_pattern --json
  "missing": [
    "no active declarations matched query terms: ['force', 'push', 'main']",
    "1 active declaration(s) matched the query but were excluded by type/subject filters"
  ],
  "search_trace": {
    "excluded_by_filters": [
      {"id": "coding.project_rule:git.no_force_push", ...}
    ], ...
  }

$ memdsl query examples/domains/coding -q "force push main"
MUST
- [coding.project_rule:git.no_force_push] Never force-push the main branch. (exceptions: []) [status=active; runtime_role=constraint; lifecycle={"status":"active"}]
```

### Try it with Claude Code in two minutes

The core library and CLI support Python 3.9+. The MCP extra and
`memdsl-mcp` server require Python 3.10+ because the upstream MCP SDK does.

```console
# Python 3.10+
pip install "memdsl[mcp]"
claude mcp add memdsl -- memdsl-mcp --workspace ~/memory   # or an examples/ dir
```

The server instructs the agent to read `memory_catalog` first, continue only
with a cursor bound to the same Source/View and filters, treat `no_match` as a
retry signal, use `memory_trace` only for bounded explicit-relation navigation,
and preflight consequential drafts against MUST constraints with
`memory_check`. Legacy `memory_map` remains registered for compatible clients.

### DeepSeek Harness

DeepSeek Harness can mount the same stdio MCP server through its official MCP
client. The recommended overlay grants only `read:summary,read:search`, so the
model can catalog, query, trace, explain, and check approved source memory but
cannot create proposals. See the tested overlay and verification steps in
[the DeepSeek Harness integration guide](docs/DEEPSEEK_HARNESS.md).

![memdsl DeepSeek Harness demo](docs/assets/deepseek-harness-demo.gif)

### Governed, typed memory

The second pillar: memory you can review like code, **without forcing one
author's ontology on every user**. Version 0.8 preserves the two-layer type
architecture introduced in 0.5 and the lifecycle-safe review contract from
0.6, then adds bounded compiled navigation and explicit workspace-v2 Views:

```text
core memory record     claim / evidence / scope / confidence / lifecycle /
                       access policy / relations

domain type system     coding.project_rule / assistant.commitment /
                       writing.voice_preference / your own memory types
```

The core owns the stable behavioral contract. A workspace owns its vocabulary.
A coding agent, personal assistant, and writing system should not have to call
the same thing a `preference`, `boundary`, or `fact` just because memdsl's
author chose those words.

### Two layers

The **core layer** provides universal fields and five stable runtime roles:

| Runtime role | EvidencePack behavior |
| --- | --- |
| `symbol` | Defines a subject that other memories can reference |
| `constraint` | Active declarations surface in MUST and participate in compliance |
| `guidance` | Active declarations surface in SHOULD |
| `assertion` | Active declarations surface in CONTEXT when relevant |
| `question` | Active declarations surface in MISSING rather than as fact |

Every searchable non-active hit is isolated under PROVISIONAL, regardless of
runtime role. Candidate symbols cannot redirect queries, and candidate
constraints cannot enter MUST or compliance.

The same authority boundary applies to relations. A `supersedes` relation can
hide a target only when its source is active and its full-id or unique bare
target resolves exactly. Candidate, retracted, archived, ambiguous, duplicate,
or wrongly prefixed superseders cannot change query, MUST, or compliance. This
is the v1 compatibility authority rule retained by 0.8. The opt-in
ResolvedView path uses the same fail-safe base and adds only explicit v2
quarantine enforcement.

The core also understands capabilities such as `requires_evidence`,
`searchable`, `temporal`, `enforceable`, `guardable`,
`exceptions_recommended`, and the explicit review opt-in
`auto_approvable`.

The **domain layer** defines meaningful memory types and compiles each one to
a runtime role. The shipped examples include:

- coding: `coding.project_rule`, `coding.bug_pattern`, `coding.tool_preference`
- personal assistant: `assistant.routine`, `assistant.commitment`,
  `assistant.relationship_context`
- writing: `writing.voice_preference`, `writing.taboo_topic`,
  `writing.style_example`

The built-in `memdsl.standard@1` pack keeps existing `entity`, `fact`,
`preference`, `boundary`, `principle`, `decision`, `state`, and `open_issue`
workspaces working. Those names are compatibility defaults, not the universal
ontology of human memory.

### Define a domain vocabulary

A workspace opts into schemas with `memdsl.json`:

```json
{
  "schema_version": "memdsl.workspace.v1",
  "sc