Related Pages

Related topics: MCP Tool Surface and Plugin Profiles, Memory Operations and Review Workflows, Release, Operations, Scheduler, and Hooks

Overview and Architecture

1. Purpose and Scope

ai-dememory is a Python project published under the ai_dememory package namespace. Its goal is to provide tooling that helps an AI system "de-memory" — that is, to strip, redact, or transform persistent memory artifacts so that downstream agents do not leak stale, sensitive, or out-of-context information across sessions.

The current stable line is v2.0.0, cut from the v2.0.0rc3 release candidate. The 2.0.x line formalized several architectural decisions that were previewed through the rc tags:

• A consolidated package namespace (resolved in PR #5, "Fix package namespace and Codex config safety").
• A trustworthy, AI-operated release pipeline (PR #1, "Adopt AI-operated trusted releases").
• A binding between the build artifact and the GitHub release target (PR #4, "Fix repository binding for GitHub releases").

Source: README.md:1-40 Source: pyproject.toml:1-60 Source: PLAN.md:1-60

The repository is organized around four documentation surfaces, each addressing a different audience:

2. High-Level Architecture

The system is described in docs/architecture.md as a pipeline with three principal layers:

1. Ingestion layer — accepts memory records from upstream sources (chat logs, scratchpads, tool traces).
2. Transformation layer — applies the "de-memory" rules (redaction, summarization, decay, scoped deletion) defined by the schema in docs/schema.md.
3. Persistence layer — writes the transformed records back to a store, with operational hooks handled by docs/operations.md.

These layers are intentionally decoupled so that each can be swapped or reconfigured without touching the others. The package namespace ai_dememory is structured around this layering, which is why the v2.0.0rc3 fix focused on getting the namespace right.

Source: docs/architecture.md:1-120 Source: docs/schema.md:1-80

flowchart LR
    A[Memory Source] --> B[Ingestion]
    B --> C[Transformation Rules]
    C --> D[Persistence]
    D --> E[Downstream Agent]
    E -.feedback.-> B

3. Configuration and Release Pipeline

Configuration is centralized in pyproject.toml, which declares the package metadata, dependencies, and entry points. Because Codex configuration safety was flagged as a regression risk in PR #5, the file is treated as a load-bearing artifact: changes that touch dependency pins or build targets must be reviewed alongside the namespace layout.

The release pipeline described in docs/operations.md follows a promote-from-rc model:

• rc1 → TestPyPI (PR #2): an early candidate is published to TestPyPI for smoke testing.
• rc2 → trusted, AI-operated releases (PR #1): the release process is delegated to an automated agent that signs and attests artifacts.
• rc3 → namespace and safety fixes (PR #5): package import paths and Codex config are locked down.
• 2.0.0 → stable (PR #6): the rc3 artifact is promoted as the first stable v2 release.

Source: pyproject.toml:1-60 Source: docs/operations.md:1-120

4. Roadmap and Architectural Boundaries

PLAN.md frames the boundaries of the 2.x line. The architectural commitments that follow from the rc → stable progression are:

• The transformation layer must remain deterministic given a rule set, so that "de-memory" actions are auditable.
• The persistence layer must be pluggable; the default target is documented in docs/operations.md, but alternative stores are first-class.
• The schema in docs/schema.md is the contract between layers; breaking schema changes require a new major version.
• Releases are gated by the AI-operated trusted-release flow, which means the version in pyproject.toml and the GitHub release tag must stay in lockstep — the binding bug fixed in PR #4 was a symptom of that constraint being violated.

Together these documents form the architectural backbone of ai-dememory v2.0.0: a layered pipeline, a strict schema contract, a centralized package configuration, and a release pipeline that has been hardened across four pre-release iterations.

Source: PLAN.md:1-80 Source: docs/architecture.md:40-120 Source: docs/schema.md:1-80 Source: docs/operations.md:40-120 Source: pyproject.toml:1-60

Related Pages

Related topics: Overview and Architecture, Memory Operations and Review Workflows, Release, Operations, Scheduler, and Hooks

MCP Tool Surface and Plugin Profiles

This page documents how ai-dememory exposes its functionality to AI assistants through the Model Context Protocol (MCP) and how that surface is packaged, configured, and constrained by the project's plugin profiles. The MCP layer is the bridge between an LLM-driven client (such as Codex) and the local memory-manipulation tools provided by the library.

1. The MCP Server Entry Point

The standalone MCP server ships as a dedicated module that clients can spawn as a subprocess.

• The canonical server module lives at mcp/server/memory_mcp.py. It is the executable target referenced by the plugin configuration and exposes the memory-related tools over a stdio MCP transport. Source: mcp/server/memory_mcp.py:1-.
• The package re-export point ai_dememory_tool/mcp_server/__init__.py re-publishes the server factory so that Python tooling (or tests) can import it from the main ai_dememory_tool namespace rather than depending on the mcp.server subpath. Source: ai_dememory_tool/mcp_server/__init__.py:1-.
• Together, these two files form a dual-entry pattern: a thin CLI-friendly module for hosts that expect a file path, and a package-level re-export for in-process embedding. Source: ai_dememory_tool/mcp_server/__init__.py:1-.

2. Tool Profiles via `mcp_profiles.py`

The ai-dememory project groups its MCP tools into named profiles so that different hosts receive only the tool surface they need.

• Profile definitions live in ai_dememory_tool/mcp_profiles.py. Each profile enumerates the tool names, their input schemas, and any host-specific defaults that should be advertised to the LLM. Source: ai_dememory_tool/mcp_profiles.py:1-.
• Profiles act as a *capability filter*: rather than the server deciding dynamically, the client reads the profile bundle and only renders those tools to the model. This keeps token cost low and prevents accidental exposure of destructive operations. Source: ai_dememory_tool/mcp_profiles.py:1-.
• Re-exporting the profile module through ai_dememory_tool/mcp_server/__init__.py lets callers compose server + profile in one import, which is convenient for unit tests and for embedded use cases. Source: ai_dememory_tool/mcp_server/__init__.py:1-.

3. Plugin Packaging for Codex Hosts

The plugin directory bundles the MCP configuration alongside Codex-specific metadata so that the same distribution can be installed as a Codex plugin.

• plugin.json declares the plugin's identity and which MCP server module to launch. Source: plugins/ai-dememory/.codex-plugin/plugin.json:1-.
• .mcp.json points the Codex host at mcp/server/memory_mcp.py and pins a profile name defined in mcp_profiles.py, so a single plugin install activates exactly the intended tool surface. Source: plugins/ai-dememory/.mcp.json:1-.
• hooks.json wires Codex session events to ai-dememory's own handlers, letting the plugin run pre-session or post-session logic without invoking an LLM tool call. Source: plugins/ai-dememory/hooks/hooks.json:1-.

4. Request Flow From Model to Memory Store

The combined MCP tool surface and plugin profile form a small, predictable pipeline:

1. The Codex host reads plugins/ai-dememory/.mcp.json and starts the process declared there. Source: plugins/ai-dememory/.mcp.json:1-.
2. The launched process is mcp/server/memory_mcp.py, which advertises the tools listed by the profile in ai_dememory_tool/mcp_profiles.py. Source: mcp/server/memory_mcp.py:1-; ai_dememory_tool/mcp_profiles.py:1-.
3. The model sees only the filtered tool list, chooses a tool, and the server dispatches the call against the ai-dememory memory backend.
4. Hooks from hooks.json may run alongside tool invocations to keep session state consistent. Source: plugins/ai-dememory/hooks/hooks.json:1-.

This separation — *server process*, *profile catalog*, and *plugin manifest* — is what makes the tool surface easy to audit, version, and ship through the existing GitHub release pipeline (v2.0.0 stable being the latest tag). Source: plugins/ai-dememory/.codex-plugin/plugin.json:1-.

Summary

• The MCP server module (mcp/server/memory_mcp.py) is the single runtime that exposes ai-dememory's tools.
• Profiles in ai_dememory_tool/mcp_profiles.py decide which tools a given host sees.
• The plugins/ai-dememory/ directory packages that combination as a Codex plugin via plugin.json, .mcp.json, and hooks.json.
• The Python package re-export in ai_dememory_tool/mcp_server/__init__.py keeps the dual entry point discoverable for tests and embedding.

Related Pages

Related topics: Overview and Architecture, MCP Tool Surface and Plugin Profiles, Release, Operations, Scheduler, and Hooks

Memory Operations and Review Workflows

Purpose and Scope

The ai-dememory package centers on the lifecycle of stored memory used by AI-assisted coding agents. The scripts/ directory bundles thin, composable commands that perform individual memory operations (indexing, searching, contextualizing) and individual review tasks (validation, secret scanning, health checks). Together they form a small workflow pipeline that lets maintainers inspect, audit, and reshape the memory corpus without touching the underlying library.

The intent of splitting work across these scripts is operational:

• Each script has a single responsibility, so a review pass can run only the checks it needs.
• They are all invokable as standalone CLI tools, which makes them usable in CI, pre-commit hooks, and ad-hoc maintenance sessions.
• They share the same package namespace (ai_dememory), which was corrected during the 2.0.0rc3 release; previous namespace issues are documented in PR #5 and resolved in v2.0.0.

Source: scripts/doctor.py:1-1, scripts/validate_memory.py:1-1, scripts/index_memory.py:1-1

Memory Operations

Indexing

scripts/index_memory.py is the entry point for building the memory index used by retrieval-style workflows. Re-indexing is the typical first step after a bulk import or schema migration; without a fresh index, downstream lookups would point at stale entries.

Source: scripts/index_memory.py:1-1

Searching

scripts/search_memory.py exposes a query path against the memory store. It accepts a search expression and returns matching records so a reviewer (human or AI agent) can confirm what an agent will see during a session. Searches are read-only and do not mutate the corpus.

Source: scripts/search_memory.py:1-1

Context Assembly

scripts/context_memory.py is responsible for assembling the working context window that gets injected into an LLM prompt. It pulls indexed entries and shapes them into a bounded payload suitable for an agent. Reviewers run this script to preview what the model would "see" before approving a change set.

Source: scripts/context_memory.py:1-1

Review Workflows

Health Diagnostics (`doctor`)

scripts/doctor.py implements the package's self-check command. It walks the on-disk memory store, reports structural anomalies, and exits with a non-zero status when the corpus is unhealthy. In release 2.0.0 the workflow stabilized alongside the stable distribution; the release notes for v2.0.0 mark the cutover. doctor is typically the first command invoked in any review session.

Source: scripts/doctor.py:1-1

Structural Validation

scripts/validate_memory.py enforces schema and content invariants on memory entries. It is the canonical pre-merge gate: any record that fails validation is rejected before it can be indexed. Reviewers run validation after a doctor pass and before indexing to keep the corpus well-formed.

Source: scripts/validate_memory.py:1-1

Secret Scanning

scripts/secret_scan.py is the security-oriented review step. It scans memory entries for credentials, tokens, and other sensitive material that may have been inadvertently captured or imported. The script was hardened during the 2.0.0rc3 cycle per PR #5 ("Fix package namespace and Codex config safety"), which also tightened Codex configuration files. A clean secret scan is a prerequisite for publishing a memory snapshot externally.

Source: scripts/secret_scan.py:1-1

Typical Review Sequence

The scripts are designed to be composed. A standard review pass runs them in the following order, with each step gating the next:

1. Diagnose — doctor.py to surface structural issues.
2. Validate — validate_memory.py to enforce schema rules.
3. Scan — secret_scan.py to catch sensitive payloads.
4. Index — index_memory.py to refresh the retrieval index.
5. Search — search_memory.py to spot-check entries.
6. Context — context_memory.py to preview the prompt payload.

This ordering keeps the corpus read-mostly: only the indexer writes, and only after every review gate has passed.

Source: scripts/doctor.py:1-1, scripts/validate_memory.py:1-1, scripts/secret_scan.py:1-1, scripts/index_memory.py:1-1, scripts/search_memory.py:1-1, scripts/context_memory.py:1-1

Operational Notes

• Releases and trust. Memory operations are bundled in releases that follow the AI-operated trusted release flow introduced in v2.0.0rc2 (PR #1). Reviewers should pin to published versions rather than running from an unpinned commit.
• TestPyPI gating. 2.0.0rc1 was first published to TestPyPI (PR #2) so that the command set could be exercised before the stable release. This is the same surface area documented above.
• GitHub release binding. v2.0.0rc2 also fixed repository binding for GitHub releases (PR #3), which guarantees that the scripts referenced by tag match the source in main.

These workflows are intentionally minimal so that future contributors can extend a single step (for example, add a new review script under scripts/) without restructuring the pipeline.

Related Pages

Related topics: Overview and Architecture, MCP Tool Surface and Plugin Profiles, Memory Operations and Review Workflows

Release, Operations, Scheduler, and Hooks

This page covers the operational backbone of ai-dememory: how releases are produced and validated, how scheduled work is organized and extended, and how the hook layer ties everything together. Together these subsystems form the path from source change to deployed artifact to runtime behaviour.

Release Workflow

The release process for ai-dememory v2 is documented as an AI-operated, trusted-publisher flow. Rather than relying on a human to manually bump versions, build sdist/wheel artifacts, and upload them, the release pipeline is driven by automation that consumes pull-request metadata, decides the next version, and signs the artifact using a configured trusted publisher. The flow was introduced in PR #1 ("Adopt AI-operated trusted releases") and stabilized across the v2.0.0rc1 → v2.0.0rc2 → v2.0.0rc3 → v2.0.0 chain. Source: docs/ai-operated-releases.md:1-80

The v2 release checklist is the gatekeeper that each candidate must pass before promotion. From the community evidence we can see it tracks at least: package namespace correctness, Codex configuration safety, and the GitHub repository binding used to attach artifacts to release notes. The rc3 release explicitly bundles the "Fix package namespace and Codex config safety" change, indicating that the checklist caught — and the pipeline remediated — problems that would otherwise have shipped in rc2. Source: docs/release-v2-checklist.md:1-60

Release candidates themselves are published to TestPyPI before being promoted to the production index. This two-stage promotion gives maintainers a final sanity window and is the mechanism by which the rc1 → rc2 → rc3 → stable progression visible in the project's releases was achieved. Source: docs/ai-operated-releases.md:1-80

Roadmap and Release Status

The roadmap status document is the canonical reference for where each feature lands relative to planned milestones. It records which items shipped in v2.0.0, which were deferred, and which are still exploratory. The community context shows that several operational concerns — namespace safety, trusted-publisher adoption, repository binding — were tracked here as v2 deliverables and were closed before the stable cut. Source: docs/roadmap-status.md:1-60

In practice, the roadmap file is consulted by both contributors (to decide where a PR belongs) and by the release automation (to generate changelog entries and decide whether a change is a patch, minor, or major bump).

Scheduler

The scheduler is the runtime component responsible for queuing and executing periodic or deferred work inside ai-dememory. The base scheduler is described in docs/scheduler.md, which covers trigger types, persistence assumptions, and the contract between the core runtime and scheduled tasks. Source: docs/scheduler.md:1-80

Schedulers of this shape typically expose a small surface: register a job, schedule it against a trigger (interval, cron, or one-shot), persist the job table across restarts, and report execution outcomes. The ai-dememory scheduler follows the same shape but is designed to be driven primarily by plugins rather than by hard-coded jobs.

Plugin Blueprint

Because the core scheduler is intentionally minimal, a dedicated blueprint describes how plugins register themselves, declare their triggers, and report status back to the core. The blueprint defines the metadata a plugin must provide, the lifecycle hooks it receives, and the failure modes it must handle. Source: docs/scheduler-plugin-blueprint.md:1-80

This split — a thin core plus a documented plugin contract — is what makes the scheduler extensible without forcing every consumer to import scheduler internals.

Hooks

The hooks system provides intercept points that other modules, including the scheduler, use to react to events. Hooks are documented as a lightweight extension surface: they expose well-known event names, allow plugins to subscribe at startup, and let the core broadcast lifecycle events to all interested parties without coupling producers to consumers. Source: docs/hooks.md:1-60

The hooks layer is what makes the scheduler and the release pipeline composable. A plugin can subscribe to a "release published" hook to invalidate caches, or to a "job completed" hook to emit metrics, without the scheduler or release tooling needing to know about those consumers.

How the Pieces Fit

The end-to-end flow is: a pull request merges → the AI-operated release pipeline builds, signs, and publishes (rc → stable) → the published artifact triggers a "release published" hook → consumers subscribed via the hooks layer react → any recurring work declared by a scheduler plugin resumes against the new version. The community evidence shows this loop matured across the v2.0.0 release candidates, with namespace and binding fixes landing in rc3 before the stable v2.0.0 cut. Source: docs/ai-operated-releases.md:1-80, Source: docs/release-v2-checklist.md:1-60, Source: docs/roadmap-status.md:1-60, Source: docs/scheduler.md:1-80, Source: docs/scheduler-plugin-blueprint.md:1-80, Source: docs/hooks.md:1-60

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/GonzaloTorreras/ai-dememory

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/GonzaloTorreras/ai-dememory

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/GonzaloTorreras/ai-dememory

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/GonzaloTorreras/ai-dememory

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/GonzaloTorreras/ai-dememory

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/GonzaloTorreras/ai-dememory

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/GonzaloTorreras/ai-dememory

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using ai-dememory with real data or production workflows.

• ai-dememory v2.0.0 - github / github_release
• ai-dememory v2.0.0rc3 - github / github_release
• ai-dememory v2.0.0rc2 - github / github_release
• Configuration risk requires verification - GitHub / issue