memdsl

memdsl

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 and the release-scope evidence freeze.

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:

$ 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.

# 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.

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:

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:

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:

{

"schema_version": "memdsl.workspace.v1", "schemas": ["coding.memschema.json"] }

The schema defines domain types, fields, roles, and capabilities:

{

"name": "coding", "version": "1", "types": { "project_rule": { "runtime_role": "constraint", "required_fields": ["claim", "evidence", "scope"], "optional_fields": ["rationale", "owner"], "search_fields": ["rationale", "owner"], "capabilities": [ "requires_evidence", "searchable", "enforceable", "guardable", "exceptions_recommended" ], "defaults": {"force": "hard", "status": "active"}, "allowed_forces": ["hard"], "allow_extra_fields": false } } }

project_rule becomes the namespaced type coding.project_rule:

module coding.memory

entity Repository.Memdsl { canonical_name: "memdsl" status: active }

coding.project_rule git.no_force_push { subject: Repository.Memdsl claim: "Never force-push the main branch." scope: repository("memdsl") confidence: high exceptions: [] rationale: "Published history must remain auditable." guard { when_any: ["push", "git", "main"] deny_any: ["force-push", "--force", "--force-with-lease"] } lifecycle { status: active } access_policy { readers: [developer, coding_agent] writers: [maintainer] reviewers: [maintainer] export: internal } evidence { source: AGENTS.md quote: "Do not force-push unless the user explicitly asks." } }

Strict schemas reject undeclared fields. Unknown memory types fail lint with unknown_memory_type; they do not silently acquire ad-hoc behavior.

Exact imports and workspace-owned dialect

Existing workspaces stay compatible: no manifest and memdsl.workspace.v1 keep legacy global linking. A workspace can explicitly audit or enforce imports with v2:

{

"schema_version": "memdsl.workspace.v2", "schemas": ["workspace-dialect.memschema.json"], "linking": {"visibility": "report"} }

use X is r