mneme-core 2.0.0__tar.gz

mneme_core-2.0.0/.gitignore

@@ -0,0 +1,88 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.pytest_cache/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual envs
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.pnpm-store/
+*.tsbuildinfo
+
+# TypeScript
+*.js.map
+*.d.ts.map
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# OS
+Thumbs.db
+desktop.ini
+
+# mneme local
+.mneme/
+*.local.json
+vault-test/
+benchmarks/results/
+benchmarks/_runs/
+benchmarks/*/output/
+benchmarks/*/result.json
+benchmarks/*/hardware.json
+
+# Secrets
+.env.local
+.env.*.local
+secrets/
+*.key
+*.pem
+
+# Build artifacts
+*.tgz
+*.whl

mneme_core-2.0.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: mneme-core
+Version: 2.0.0
+Summary: Vault-native memory engine for Claude Code. FTS5 BM25, RRF-ready retrieval, gated Graphiti KG, and adaptive context tooling.
+Project-URL: Homepage, https://github.com/TheGoatPsy/mneme
+Project-URL: Documentation, https://github.com/TheGoatPsy/mneme/tree/main/docs
+Project-URL: Repository, https://github.com/TheGoatPsy/mneme.git
+Project-URL: Issues, https://github.com/TheGoatPsy/mneme/issues
+Project-URL: Changelog, https://github.com/TheGoatPsy/mneme/blob/main/CHANGELOG.md
+Author: Onour Impram
+License: MIT
+Keywords: claude-code,fts5,graphiti,knowledge-graph,markdown,mcp,memory,rrf
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.11
+Requires-Dist: click<9,>=8.1
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: structlog<25,>=24.1
+Provides-Extra: compression
+Requires-Dist: anthropic<1,>=0.28; extra == 'compression'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.4.7; extra == 'dev'
+Requires-Dist: testcontainers>=4.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: anthropic<1,>=0.28; extra == 'full'
+Requires-Dist: graphiti-core<1,>=0.3; extra == 'full'
+Requires-Dist: neo4j<6,>=5.21; extra == 'full'
+Requires-Dist: onnxruntime<2,>=1.18; extra == 'full'
+Provides-Extra: standard
+Requires-Dist: onnxruntime<2,>=1.18; extra == 'standard'
+Description-Content-Type: text/markdown
+
+# mneme-core
+
+Python core for [mneme](https://github.com/TheGoatPsy/mneme): vault-native memory for Claude Code, also usable from Codex and any MCP client. mneme is Claude-Code-native by origin and client-neutral at the core.
+
+This package provides:
+
+- FTS5 BM25 full-text indexer with language-aware normalization (Turkish casefold module included as utility).
+- RRF-ready retrieval pipeline at `k=60`, with FTS5 shipped and optional backends injectable by callers.
+- Graphiti bi-temporal knowledge graph adapter, gated by the full profile and local Neo4j.
+- Roadmap dense embedding adapter. The v1.0 standard profile reserves the runtime slot but does not ship packaged LEANN retrieval.
+- Background compression pipeline with 4-D rubric (Accuracy, Depth, Context, Continuity) and cost cap ledger.
+- Adaptive Context Layer: `distill.shell_compress`, `distill.injection_dedup`, `distill.adaptive_topk`, `distill.compressed_format`, and the `mneme audit` CLI.
+
+## Installation
+
+```bash
+pip install mneme-core
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quality Gates
+
+This package targets Python 3.11+ and passes `ruff` lint plus `mypy --strict`. Test coverage minimum is 80 percent for business logic.
+
+## License
+
+MIT. See LICENSE in the repository root.

mneme_core-2.0.0/README.md

@@ -0,0 +1,32 @@
+# mneme-core
+
+Python core for [mneme](https://github.com/TheGoatPsy/mneme): vault-native memory for Claude Code, also usable from Codex and any MCP client. mneme is Claude-Code-native by origin and client-neutral at the core.
+
+This package provides:
+
+- FTS5 BM25 full-text indexer with language-aware normalization (Turkish casefold module included as utility).
+- RRF-ready retrieval pipeline at `k=60`, with FTS5 shipped and optional backends injectable by callers.
+- Graphiti bi-temporal knowledge graph adapter, gated by the full profile and local Neo4j.
+- Roadmap dense embedding adapter. The v1.0 standard profile reserves the runtime slot but does not ship packaged LEANN retrieval.
+- Background compression pipeline with 4-D rubric (Accuracy, Depth, Context, Continuity) and cost cap ledger.
+- Adaptive Context Layer: `distill.shell_compress`, `distill.injection_dedup`, `distill.adaptive_topk`, `distill.compressed_format`, and the `mneme audit` CLI.
+
+## Installation
+
+```bash
+pip install mneme-core
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quality Gates
+
+This package targets Python 3.11+ and passes `ruff` lint plus `mypy --strict`. Test coverage minimum is 80 percent for business logic.
+
+## License
+
+MIT. See LICENSE in the repository root.

mneme_core-2.0.0/pyproject.toml

@@ -0,0 +1,125 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mneme-core"
+version = "2.0.0"
+description = "Vault-native memory engine for Claude Code. FTS5 BM25, RRF-ready retrieval, gated Graphiti KG, and adaptive context tooling."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Onour Impram" }]
+keywords = ["claude-code", "memory", "fts5", "rrf", "graphiti", "knowledge-graph", "markdown", "mcp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing :: Indexing"
+]
+dependencies = [
+    "pydantic>=2.7,<3",
+    "structlog>=24.1,<25",
+    "click>=8.1,<9",
+    "pyyaml>=6.0,<7"
+]
+
+[project.optional-dependencies]
+# Standard profile: reserved runtime slot for the roadmap dense adapter.
+# v1.0 ships the RRF protocol and FTS5 leg; the packaged LEANN adapter
+# is intentionally not advertised as shipped.
+standard = [
+    "onnxruntime>=1.18,<2"
+]
+
+# Full profile: temporal knowledge graph. Adds Neo4j driver and the
+# Graphiti episode/community engine. Lite/standard profiles never
+# import these, and ``mneme_core.kg`` modules lazy-import graphiti_core
+# so installing without this extra is a clean no-op.
+full = [
+    "onnxruntime>=1.18,<2",
+    "neo4j>=5.21,<6",
+    "graphiti-core>=0.3,<1",
+    "anthropic>=0.28,<1"
+]
+
+# Background AI compression (Phase F) lives behind an opt-in flag and
+# needs an Anthropic client. The compression code path is feature-
+# gated on the operator setting ``compression_enabled = true`` plus
+# the API key being present in env, so the dep itself is cheap.
+compression = [
+    "anthropic>=0.28,<1"
+]
+
+dev = [
+    "pytest>=8.2",
+    "pytest-cov>=5.0",
+    "ruff>=0.4.7",
+    "mypy>=1.10",
+    "types-PyYAML>=6.0",
+    "testcontainers>=4.0"
+]
+
+[project.scripts]
+# Standalone core exposes its CLI as `mneme-core`. The user-facing
+# `mneme` command is owned solely by mneme-cc-plugin, which re-registers
+# these core command groups under it. Both packages previously declared a
+# `mneme` script, so a co-install resolved to whichever pip wrote last.
+mneme-core = "mneme_core.cli:main"
+mneme-audit = "mneme_core.distill.audit:main"
+mneme-modes = "mneme_core.modes_cli:main"
+mneme-console = "mneme_core.console:main"
+
+[project.urls]
+Homepage = "https://github.com/TheGoatPsy/mneme"
+Documentation = "https://github.com/TheGoatPsy/mneme/tree/main/docs"
+Repository = "https://github.com/TheGoatPsy/mneme.git"
+Issues = "https://github.com/TheGoatPsy/mneme/issues"
+Changelog = "https://github.com/TheGoatPsy/mneme/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mneme_core"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/mneme_core/compression/prompts/compress-en.md" = "mneme_core/compression/prompts/compress-en.md"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "C4", "SIM"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+files = ["src/mneme_core"]
+
+[[tool.mypy.overrides]]
+# Optional-profile dependencies. lite/standard installs (and the CI
+# type-check env, which installs only [dev]) do not have these; the code
+# lazy-imports them behind runtime feature gates, so missing stubs here
+# are expected rather than a type error.
+module = ["graphiti_core.*", "neo4j.*", "anthropic.*", "onnxruntime.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+addopts = "-v --strict-markers --cov=mneme_core --cov-report=term-missing --cov-fail-under=80"
+
+[tool.coverage.run]
+branch = true
+source = ["mneme_core"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]

mneme_core-2.0.0/src/mneme_core/__init__.py

@@ -0,0 +1,4 @@
+"""mneme-core: vault-native memory engine for Claude Code."""
+
+__version__ = "2.0.0"
+__all__ = ["__version__"]

mneme_core-2.0.0/src/mneme_core/__main__.py

@@ -0,0 +1,8 @@
+"""Module execution entry point for ``python -m mneme_core``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

mneme_core-2.0.0/src/mneme_core/approval.py

@@ -0,0 +1,183 @@
+"""Human-approval gate for memory edits (conflict-resolution #4).
+
+An agent *proposes* a memory edit; the proposal starts in ``PENDING`` status.
+Edits in *durable* categories (IDENTITY, PREFERENCE, CLINICAL, LEGAL,
+FINANCIAL) must receive explicit human approval before they may be applied.
+Edits in the EPHEMERAL category (session notes, observations) may be applied
+while still PENDING.  A REJECTED proposal can never be applied.
+
+All user-supplied content is passed through :func:`mneme_core.privacy.redact`
+before being stored in the proposal.  Proposal IDs are deterministic
+(``uuid.uuid5``) so re-proposing identical inputs yields the same ID.
+
+Pure, deterministic, no IO, no network, no clock.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import uuid
+from dataclasses import dataclass
+from enum import Enum
+
+from .privacy import redact
+
+# ---------------------------------------------------------------------------
+# Enumerations
+# ---------------------------------------------------------------------------
+
+_NAMESPACE = uuid.UUID("6ba7b810-9dad-11d1-80b4-00c04fd430c8")  # NAMESPACE_URL
+
+
+class ProposalStatus(str, Enum):  # noqa: UP042
+    """Lifecycle status of a :class:`MemoryProposal`.
+
+    Inherits ``str`` so instances serialise directly as JSON strings and
+    compare equal to their string values without an extra ``.value`` call.
+    ``UP042`` suppresses the Ruff suggestion to use ``StrEnum`` (Python 3.11+)
+    to stay consistent with the ``str`` + ``Enum`` pattern used elsewhere.
+    """
+
+    PENDING = "PENDING"
+    APPROVED = "APPROVED"
+    REJECTED = "REJECTED"
+
+
+class EditCategory(str, Enum):  # noqa: UP042
+    """Semantic category of the memory edit being proposed.
+
+    * **EPHEMERAL** — low-stakes session/topic/observation; may be applied
+      without explicit approval.
+    * All other categories are *durable* and require human approval.
+    """
+
+    EPHEMERAL = "EPHEMERAL"
+    IDENTITY = "IDENTITY"
+    PREFERENCE = "PREFERENCE"
+    CLINICAL = "CLINICAL"
+    LEGAL = "LEGAL"
+    FINANCIAL = "FINANCIAL"
+
+
+#: Categories that require explicit human approval before an edit may be applied.
+DURABLE_CATEGORIES: frozenset[EditCategory] = frozenset(
+    {
+        EditCategory.IDENTITY,
+        EditCategory.PREFERENCE,
+        EditCategory.CLINICAL,
+        EditCategory.LEGAL,
+        EditCategory.FINANCIAL,
+    }
+)
+
+# ---------------------------------------------------------------------------
+# Proposal dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class MemoryProposal:
+    """An immutable record of a proposed memory edit.
+
+    Attributes
+    ----------
+    proposal_id:
+        Deterministic ``uuid5`` derived from ``action``, ``target_path``, and
+        the *redacted* content.  Identical inputs always produce the same ID.
+    action:
+        ``"create"`` | ``"update"`` | ``"delete"``.
+    target_path:
+        Vault-relative path of the note being created/modified/deleted.
+    content:
+        Proposed note content **after** redaction via
+        :func:`mneme_core.privacy.redact`.
+    category:
+        Semantic category governing approval requirements.
+    status:
+        Current lifecycle status (PENDING / APPROVED / REJECTED).
+    trust:
+        Proposer identity string; defaults to ``"agent"``.
+    """
+
+    proposal_id: str
+    action: str
+    target_path: str
+    content: str
+    category: EditCategory
+    status: ProposalStatus
+    trust: str
+
+
+# ---------------------------------------------------------------------------
+# Pure functions
+# ---------------------------------------------------------------------------
+
+
+def requires_human_approval(category: EditCategory) -> bool:
+    """Return ``True`` iff *category* is in :data:`DURABLE_CATEGORIES`."""
+    return category in DURABLE_CATEGORIES
+
+
+def propose(
+    *,
+    action: str,
+    target_path: str,
+    content: str,
+    category: EditCategory,
+    trust: str = "agent",
+) -> MemoryProposal:
+    """Create a new :class:`MemoryProposal` in PENDING status.
+
+    Content is redacted via :func:`~mneme_core.privacy.redact` before being
+    stored.  The ``proposal_id`` is a deterministic ``uuid5`` derived from
+    ``action + NUL + target_path + NUL + redacted_content`` so that identical
+    inputs always yield the same proposal ID.
+    """
+    redacted = redact(content)
+    # category and trust are part of proposal identity: an EPHEMERAL and a
+    # CLINICAL proposal for the same path+content must NOT share a proposal_id,
+    # else a downstream store keyed on it could alias the durable edit to an
+    # already-applied ephemeral one and bypass the human-approval gate.
+    seed = f"{action}\x00{target_path}\x00{category.value}\x00{trust}\x00{redacted}"
+    proposal_id = str(uuid.uuid5(_NAMESPACE, seed))
+    return MemoryProposal(
+        proposal_id=proposal_id,
+        action=action,
+        target_path=target_path,
+        content=redacted,
+        category=category,
+        status=ProposalStatus.PENDING,
+        trust=trust,
+    )
+
+
+def approve(proposal: MemoryProposal) -> MemoryProposal:
+    """Return a copy of *proposal* with ``status`` set to APPROVED.
+
+    Idempotent: approving an already-approved proposal returns an equivalent
+    object unchanged.
+    """
+    return dataclasses.replace(proposal, status=ProposalStatus.APPROVED)
+
+
+def reject(proposal: MemoryProposal) -> MemoryProposal:
+    """Return a copy of *proposal* with ``status`` set to REJECTED."""
+    return dataclasses.replace(proposal, status=ProposalStatus.REJECTED)
+
+
+def can_apply(proposal: MemoryProposal) -> bool:
+    """Return ``True`` iff the proposal may be applied to the vault.
+
+    Rules (deterministic, pure):
+
+    * A REJECTED proposal can **never** be applied.
+    * An APPROVED proposal can always be applied.
+    * A PENDING proposal may be applied only when its category is EPHEMERAL
+      (i.e. ``requires_human_approval`` is ``False``).
+    """
+    if proposal.status == ProposalStatus.REJECTED:
+        return False
+    if proposal.status == ProposalStatus.APPROVED:
+        return True
+    # PENDING: allowed only for non-durable (ephemeral) categories.
+    return not requires_human_approval(proposal.category)

mneme_core-2.0.0/src/mneme_core/audit.py

@@ -0,0 +1,82 @@
+"""Read-only vault audit aggregator (the console surface, v1).
+
+Produces a deterministic, read-only snapshot of the vault: note counts by
+memory type plus a security-scan summary. This is the programmatic/text console
+surface; a browser audit UI (timeline, graph explorer, token-ROI dashboard) is
+deferred. The aggregator never writes and never raises on a single bad file.
+
+No LLM, no network.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .security import scan_vault, summarize
+from .vault.frontmatter import parse
+
+
+@dataclass(frozen=True)
+class AuditReport:
+    """A read-only vault health + safety snapshot."""
+
+    note_count: int
+    type_counts: dict[str, int]
+    security: dict[str, Any]
+
+
+def build_audit(vault_root: Path) -> AuditReport:
+    """Walk the vault markdown and build a read-only audit snapshot.
+
+    Counts notes by frontmatter ``type`` (notes without parseable frontmatter
+    are bucketed as ``"(none)"``) and folds in a security-scan summary. Symlinks
+    that escape the vault are skipped; unreadable or malformed files never crash
+    the audit.
+    """
+    root_resolved = vault_root.resolve()
+    type_counts: dict[str, int] = {}
+    note_count = 0
+    for md_path in sorted(vault_root.rglob("*.md")):
+        try:
+            resolved = md_path.resolve()
+        except OSError:
+            continue
+        if not resolved.is_relative_to(root_resolved):
+            continue
+        try:
+            text = md_path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        note_count += 1
+        type_name = "(none)"
+        try:
+            front, _ = parse(text)
+            if front is not None and front.type:
+                type_name = front.type
+        except Exception:  # noqa: BLE001 - audit must never crash on a bad note
+            type_name = "(unparseable)"
+        type_counts[type_name] = type_counts.get(type_name, 0) + 1
+
+    security = summarize(scan_vault(vault_root))
+    return AuditReport(note_count=note_count, type_counts=type_counts, security=security)
+
+
+def render_audit(report: AuditReport) -> str:
+    """Render an :class:`AuditReport` as a plain-text report."""
+    lines = ["# Vault audit", "", f"Notes: {report.note_count}", "", "## By type"]
+    if report.type_counts:
+        for type_name, count in sorted(report.type_counts.items()):
+            lines.append(f"- {type_name}: {count}")
+    else:
+        lines.append("- (no notes)")
+    lines.extend(["", "## Security"])
+    sec = report.security
+    lines.append(f"- files flagged: {sec.get('files_flagged', 0)}")
+    lines.append(f"- total findings: {sec.get('total_findings', 0)}")
+    by_kind = sec.get("by_kind", {})
+    if isinstance(by_kind, dict):
+        for kind, count in sorted(by_kind.items()):
+            lines.append(f"  - {kind}: {count}")
+    return "\n".join(lines) + "\n"

mneme_core-2.0.0/src/mneme_core/bench/__init__.py

@@ -0,0 +1,40 @@
+"""Benchmark helpers shared by the ``benchmarks/`` runner scripts.
+
+Three focused submodules:
+
+* :mod:`mneme_core.bench.metrics` - information-retrieval metric primitives
+  (nDCG@k, Recall@k, MRR) plus quantile helpers for latency distributions.
+* :mod:`mneme_core.bench.synth` - deterministic synthetic corpus and query
+  generator. Tests and benchmarks both lean on this so they exercise the
+  same shape of data.
+* :mod:`mneme_core.bench.hardware` - hardware/runtime probe that emits
+  ``hardware.json`` next to every benchmark result for reproducibility.
+
+The submodules are intentionally small and side-effect-free. Bench scripts
+own their own argparse, output, and CI guards.
+"""
+
+from .hardware import HardwareSnapshot, capture_hardware
+from .metrics import (
+    mean_reciprocal_rank,
+    ndcg_at_k,
+    percentiles,
+    recall_at_k,
+)
+from .synth import (
+    SyntheticCorpus,
+    SyntheticQuery,
+    build_synthetic_corpus,
+)
+
+__all__ = [
+    "HardwareSnapshot",
+    "SyntheticCorpus",
+    "SyntheticQuery",
+    "build_synthetic_corpus",
+    "capture_hardware",
+    "mean_reciprocal_rank",
+    "ndcg_at_k",
+    "percentiles",
+    "recall_at_k",
+]