plain-text-memory-mcp 0.1.0__py3-none-any.whl

plain_text_memory_mcp/__init__.py

@@ -0,0 +1 @@
+"""Knowledge-graph memory MCP server with date and agent tags."""

plain_text_memory_mcp/agent.py

@@ -0,0 +1,24 @@
+"""Name the agent that is calling the memory server."""
+
+UNKNOWN_AGENT = "unknown"
+
+KNOWN_AGENTS = (("claude", "claude-code"), ("codex", "codex"))
+
+
+def calc_agent_name(client_name: str | None, override: str | None) -> str:
+    """Return the agent name recorded in memory tags.
+
+    - A non-blank override, from `MEMORY_AGENT`, always wins.
+    - Client names containing "claude" or "codex" map to `claude-code` and
+      `codex`; any other name is recorded as sent.
+    - A missing or blank client name records `unknown`.
+    """
+    if override and override.strip():
+        return override.strip()
+    if not client_name or not client_name.strip():
+        return UNKNOWN_AGENT
+    lowered = client_name.lower()
+    for marker, agent_name in KNOWN_AGENTS:
+        if marker in lowered:
+            return agent_name
+    return client_name.strip()

plain_text_memory_mcp/graph.py

@@ -0,0 +1,320 @@
+"""Model the tagged knowledge graph and its pure operations."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import TypedDict
+
+RelationKey = tuple[str, str, str]
+
+
+@dataclass(frozen=True)
+class Tag:
+    """Record when an entry was added and which agent added it."""
+
+    added_at: str | None
+    agent: str | None
+
+
+UNTAGGED = Tag(None, None)
+
+
+@dataclass(frozen=True)
+class Observation:
+    """Hold one tagged fact about an entity."""
+
+    text: str
+    tag: Tag
+
+
+@dataclass
+class Entity:
+    """Hold a named node and its observations."""
+
+    name: str
+    entity_type: str
+    observations: list[Observation]
+    tag: Tag
+
+
+@dataclass(frozen=True)
+class Relation:
+    """Hold a directed, typed edge between two entity names."""
+
+    source: str
+    target: str
+    relation_type: str
+    tag: Tag
+
+
+@dataclass(frozen=True)
+class Header:
+    """Record which repo a memory file belongs to."""
+
+    repo_name: str
+    repo_root: str
+    tag: Tag
+
+
+@dataclass
+class Graph:
+    """Hold every entity and relation in one memory file.
+
+    - `header` is None until the first write stamps the owning repo.
+    """
+
+    entities: list[Entity] = field(default_factory=list)
+    relations: list[Relation] = field(default_factory=list)
+    header: Header | None = None
+
+
+class UsageCounts(TypedDict):
+    """Count the entries in one memory file."""
+
+    entities: int
+    observations: int
+    relations: int
+
+
+class Usage(TypedDict):
+    """Summarize what one memory file contains."""
+
+    counts: UsageCounts
+    entity_types: dict[str, int]
+    relation_types: dict[str, int]
+    agents: dict[str, int]
+
+
+class EntityNotFoundError(LookupError):
+    """Raised when an operation names an entity that does not exist."""
+
+
+def init_tag(agent: str, now: datetime | None = None) -> Tag:
+    """Return a tag for the given agent stamped with local time.
+
+    - `now` exists for tests; production callers omit it.
+    """
+    moment = now or datetime.now().astimezone()
+    return Tag(moment.isoformat(timespec="seconds"), agent)
+
+
+def init_header(repo_root: Path, tag: Tag) -> Header:
+    """Return a header naming `repo_root` as the memory file's owner."""
+    return Header(repo_root.name, repo_root.as_posix(), tag)
+
+
+def build_entity(
+    name: str, entity_type: str, texts: list[str], tag: Tag
+) -> Entity:
+    """Return a new entity whose observations all carry the given tag.
+
+    - Repeated texts are kept once, in first-seen order.
+    """
+    unique_texts = dict.fromkeys(texts)
+    observations = [Observation(text, tag) for text in unique_texts]
+    return Entity(name, entity_type, observations, tag)
+
+
+def look_entity(memory: Graph, name: str) -> Entity | None:
+    """Return the entity with the given name, or None."""
+    for entity in memory.entities:
+        if entity.name == name:
+            return entity
+    return None
+
+
+def create_entities(memory: Graph, entities: list[Entity]) -> list[Entity]:
+    """Append entities whose names are new and return the ones appended."""
+    known_names = {entity.name for entity in memory.entities}
+    created: list[Entity] = []
+    for entity in entities:
+        if entity.name in known_names:
+            continue
+        known_names.add(entity.name)
+        memory.entities.append(entity)
+        created.append(entity)
+    return created
+
+
+def _relation_key(relation: Relation) -> RelationKey:
+    return (relation.source, relation.target, relation.relation_type)
+
+
+def look_missing_names(memory: Graph, relation: Relation) -> list[str]:
+    """Return the relation's endpoint names that name no entity, once each."""
+    known_names = {entity.name for entity in memory.entities}
+    endpoints = dict.fromkeys((relation.source, relation.target))
+    return [name for name in endpoints if name not in known_names]
+
+
+def create_relations(
+    memory: Graph, relations: list[Relation]
+) -> list[Relation]:
+    """Append relations that are new by content and return them.
+
+    - Two relations with the same endpoints and relation type are duplicates
+      even when their tags differ.
+    - Relations naming an entity that does not exist are skipped; see
+      `look_missing_names`.
+    """
+    known_keys = {_relation_key(relation) for relation in memory.relations}
+    created: list[Relation] = []
+    for relation in relations:
+        key = _relation_key(relation)
+        if key in known_keys or look_missing_names(memory, relation):
+            continue
+        known_keys.add(key)
+        memory.relations.append(relation)
+        created.append(relation)
+    return created
+
+
+def update_observations(
+    memory: Graph, entity_name: str, texts: list[str], tag: Tag
+) -> list[Observation]:
+    """Append new observation texts to an entity and return the added ones.
+
+    - Texts already on the entity are skipped and keep their original tag.
+    - Raises `EntityNotFoundError` when the entity does not exist.
+    """
+    entity = look_entity(memory, entity_name)
+    if entity is None:
+        message = f"Entity with name {entity_name} not found"
+        raise EntityNotFoundError(message)
+    known_texts = {observation.text for observation in entity.observations}
+    added: list[Observation] = []
+    for text in texts:
+        if text in known_texts:
+            continue
+        known_texts.add(text)
+        observation = Observation(text, tag)
+        entity.observations.append(observation)
+        added.append(observation)
+    return added
+
+
+def _split[T](items: list[T], is_doomed: Callable[[T], bool]) -> list[T]:
+    """Remove items matching `is_doomed` in place and return them."""
+    removed = [item for item in items if is_doomed(item)]
+    items[:] = [item for item in items if not is_doomed(item)]
+    return removed
+
+
+def remove_entities(
+    memory: Graph, names: list[str]
+) -> tuple[list[Entity], list[Relation]]:
+    """Remove the named entities and every relation that touches them.
+
+    - Returns the removed entities and relations; unknown names are ignored.
+    """
+    doomed = set(names)
+    entities = _split(memory.entities, lambda e: e.name in doomed)
+    relations = _split(
+        memory.relations,
+        lambda r: r.source in doomed or r.target in doomed,
+    )
+    return entities, relations
+
+
+def remove_observations(
+    memory: Graph, entity_name: str, texts: list[str]
+) -> list[Observation]:
+    """Remove observations by text and return the removed ones.
+
+    - A missing entity or text is ignored.
+    """
+    entity = look_entity(memory, entity_name)
+    if entity is None:
+        return []
+    doomed = set(texts)
+    return _split(entity.observations, lambda o: o.text in doomed)
+
+
+def remove_relations(memory: Graph, keys: list[RelationKey]) -> list[Relation]:
+    """Remove relations matching a key and return the removed ones.
+
+    - A key matches on endpoints and relation type, ignoring the tag.
+    """
+    doomed = set(keys)
+    return _split(memory.relations, lambda r: _relation_key(r) in doomed)
+
+
+def _filter_to_entities(memory: Graph, entities: list[Entity]) -> Graph:
+    names = {entity.name for entity in entities}
+    relations = [
+        relation
+        for relation in memory.relations
+        if relation.source in names and relation.target in names
+    ]
+    return Graph(entities, relations)
+
+
+def _is_query_match(entity: Entity, needle: str) -> bool:
+    if needle in entity.name.lower() or needle in entity.entity_type.lower():
+        return True
+    return any(
+        needle in observation.text.lower()
+        for observation in entity.observations
+    )
+
+
+def filter_by_query(memory: Graph, query: str) -> Graph:
+    """Return entities matching a case-insensitive substring query.
+
+    - Matches entity name, entity type, and observation text.
+    - Keeps only relations whose both endpoints matched.
+    """
+    needle = query.lower()
+    matches = [
+        entity for entity in memory.entities if _is_query_match(entity, needle)
+    ]
+    return _filter_to_entities(memory, matches)
+
+
+def filter_by_names(memory: Graph, names: list[str]) -> Graph:
+    """Return the named entities and the relations between them."""
+    wanted = set(names)
+    matches = [entity for entity in memory.entities if entity.name in wanted]
+    return _filter_to_entities(memory, matches)
+
+
+def _count_sorted(names: list[str]) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for name in names:
+        counts[name] = counts.get(name, 0) + 1
+    return dict(sorted(counts.items()))
+
+
+def calc_usage(memory: Graph) -> Usage:
+    """Return counts of entries, entity and relation types, and agents.
+
+    - Agents are counted over entities, observations, and relations;
+      untagged entries count as `untagged`.
+    """
+    observations = [
+        observation
+        for entity in memory.entities
+        for observation in entity.observations
+    ]
+    tags = [
+        *(entity.tag for entity in memory.entities),
+        *(observation.tag for observation in observations),
+        *(relation.tag for relation in memory.relations),
+    ]
+    return {
+        "counts": {
+            "entities": len(memory.entities),
+            "observations": len(observations),
+            "relations": len(memory.relations),
+        },
+        "entity_types": _count_sorted(
+            [entity.entity_type for entity in memory.entities]
+        ),
+        "relation_types": _count_sorted(
+            [relation.relation_type for relation in memory.relations]
+        ),
+        "agents": _count_sorted([tag.agent or "untagged" for tag in tags]),
+    }

plain_text_memory_mcp/prompts/cleanup.md

@@ -0,0 +1,37 @@
+# Memory cleanup
+
+Review this repo's plain-text-memory graph and propose a cleanup. Deleting
+memory cannot be undone, so work in two phases: propose, then apply only
+what I approve. A request to clean up is a request for a proposal, not
+permission to delete.
+
+## Phase 1: propose
+
+1. Read the graph with `read_graph`.
+1. For each candidate, check the repo before judging it. When two
+   observations contradict each other, the code decides which one is true,
+   not the newer `added_at`. When the repo cannot settle it, mark the item
+   "ask".
+1. Present one table and stop:
+
+| # | Entity | Item | Action | Evidence |
+| --- | --- | --- | --- | --- |
+| 1 | reading_list | "Tests run with unittest" | delete | `pyproject.toml` configures pytest |
+| 2 | readinglist | whole entity | merge into reading_list | same repo, misspelled name |
+
+Actions are `delete`, `merge into <entity>`, `rewrite`, `keep`, or `ask`.
+Entries marked "safe to delete" or starting with `TEST:` are ordinary
+`delete` rows. They still wait for my approval.
+
+## Phase 2: apply
+
+Apply only the rows I approve, then list what changed. The delete tools
+return everything they deleted.
+
+A merge re-adds observations with `add_observations`, which stamps them with
+today's date and the current agent; the originals' tags are lost. Say so in
+the merge row so I can choose `keep` instead.
+
+Go back to phase 1 instead of deleting anything I have not seen in the
+table, settling a contradiction by date alone, or treating "safe to delete"
+or empty tags as approval.

plain_text_memory_mcp/prompts/export.md

@@ -0,0 +1,20 @@
+# Memory export
+
+Export this repo's plain-text-memory taxonomy.
+
+1. Call `export_taxonomy`. It writes `.agents/memory.local.taxonomy.jsonc`
+   beside the memory file, holding the server's versioned taxonomy and this
+   repo's usage: entry counts, entity and relation types in use, and entries
+   per agent. Running it again overwrites the file with current data.
+1. Confirm `.gitignore` ignores the export with the line
+   `.agents/*memory.local.*`; replace an older `.agents/*memory.local.jsonl*`
+   line with it. Add it if missing and tell me.
+1. Report in two or three lines: the file path, `taxonomy_version`, and the
+   entity, observation, and relation counts.
+1. If two entity or relation types in the file look like the same thing
+   spelled differently, such as `library` and `libraries`, name them and
+   suggest the cleanup prompt. Change nothing yourself.
+
+If the tool reports that the memory file belongs to another repo, resolve
+that with `initialize_memory` first, then export again. A repo with no
+memory yet still exports, with zero counts.

plain_text_memory_mcp/records.py

@@ -0,0 +1,233 @@
+"""Map graph models to and from JSONL records.
+
+- Key names match the original server where they overlap: `entityType`,
+  `relationType`, `from`, and `to`.
+- Records written before tagging existed load with `UNTAGGED`.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+from plain_text_memory_mcp.graph import (
+    UNTAGGED,
+    Entity,
+    Graph,
+    Header,
+    Observation,
+    Relation,
+    Tag,
+)
+
+Record = dict[str, object]
+
+
+class ObservationRecord(TypedDict):
+    """One observation as JSON, inside an entity's observations list."""
+
+    text: str
+    added_at: str | None
+    agent: str | None
+
+
+class EntityRecord(TypedDict):
+    """One entity line of the memory file."""
+
+    type: Literal["entity"]
+    name: str
+    entityType: str
+    added_at: str | None
+    agent: str | None
+    observations: list[ObservationRecord]
+
+
+# Functional form: "from" is a Python keyword.
+RelationRecord = TypedDict(
+    "RelationRecord",
+    {
+        "type": Literal["relation"],
+        "from": str,
+        "to": str,
+        "relationType": str,
+        "added_at": str | None,
+        "agent": str | None,
+    },
+)
+RelationRecord.__doc__ = "One relation line of the memory file."
+
+
+class HeaderRecord(TypedDict):
+    """The header line naming the repo that owns the memory file."""
+
+    type: Literal["header"]
+    repo_name: str
+    repo_root: str
+    added_at: str | None
+    agent: str | None
+
+
+class GraphRecord(TypedDict):
+    """Entities and the relations between them, as tools return them."""
+
+    entities: list[EntityRecord]
+    relations: list[RelationRecord]
+
+
+# What each record type is for; published in the taxonomy and its export.
+RECORD_PURPOSES = {
+    "header": (
+        "First line of the memory file. Names the repo that owns it, so a"
+        " copy in another repo is detected."
+    ),
+    "entity": (
+        "A named thing the agents remember, such as a repo, module, library,"
+        " person, or decision, with its observations."
+    ),
+    "relation": (
+        "A directed link between two entities, in active voice:"
+        " reading_list uses sqlite."
+    ),
+    "observation": (
+        "One fact about an entity, stored inside the entity's observations"
+        " list."
+    ),
+}
+
+
+class RecordError(ValueError):
+    """Raised when a memory record does not match the expected shape."""
+
+
+def to_observation_record(observation: Observation) -> ObservationRecord:
+    """Return the JSON record for one observation."""
+    return {
+        "text": observation.text,
+        "added_at": observation.tag.added_at,
+        "agent": observation.tag.agent,
+    }
+
+
+def to_entity_record(entity: Entity) -> EntityRecord:
+    """Return the JSON record for one entity and its observations."""
+    return {
+        "type": "entity",
+        "name": entity.name,
+        "entityType": entity.entity_type,
+        "added_at": entity.tag.added_at,
+        "agent": entity.tag.agent,
+        "observations": [
+            to_observation_record(observation)
+            for observation in entity.observations
+        ],
+    }
+
+
+def to_relation_record(relation: Relation) -> RelationRecord:
+    """Return the JSON record for one relation."""
+    return {
+        "type": "relation",
+        "from": relation.source,
+        "to": relation.target,
+        "relationType": relation.relation_type,
+        "added_at": relation.tag.added_at,
+        "agent": relation.tag.agent,
+    }
+
+
+def to_header_record(header: Header) -> HeaderRecord:
+    """Return the JSON record for the memory file's owning repo."""
+    return {
+        "type": "header",
+        "repo_name": header.repo_name,
+        "repo_root": header.repo_root,
+        "added_at": header.tag.added_at,
+        "agent": header.tag.agent,
+    }
+
+
+def to_graph_record(memory: Graph) -> GraphRecord:
+    """Return a JSON record holding every entity and relation."""
+    return {
+        "entities": [to_entity_record(entity) for entity in memory.entities],
+        "relations": [
+            to_relation_record(relation) for relation in memory.relations
+        ],
+    }
+
+
+def _parse_tag(raw: dict[str, object]) -> Tag:
+    added_at = raw.get("added_at")
+    agent = raw.get("agent")
+    if added_at is None and agent is None:
+        return UNTAGGED
+    return Tag(
+        added_at if isinstance(added_at, str) else None,
+        agent if isinstance(agent, str) else None,
+    )
+
+
+def _parse_text(raw: dict[str, object], key: str) -> str:
+    value = raw.get(key)
+    if not isinstance(value, str):
+        message = f"field {key!r} must be a string, found {value!r}"
+        raise RecordError(message)
+    return value
+
+
+def _parse_observation(raw: object) -> Observation:
+    if isinstance(raw, str):
+        return Observation(raw, UNTAGGED)
+    if isinstance(raw, dict):
+        return Observation(_parse_text(raw, "text"), _parse_tag(raw))
+    message = f"observation must be a string or object, found {raw!r}"
+    raise RecordError(message)
+
+
+def _parse_entity(raw: dict[str, object]) -> Entity:
+    observations = raw.get("observations", [])
+    if not isinstance(observations, list):
+        message = f"observations must be a list, found {observations!r}"
+        raise RecordError(message)
+    return Entity(
+        _parse_text(raw, "name"),
+        _parse_text(raw, "entityType"),
+        [_parse_observation(observation) for observation in observations],
+        _parse_tag(raw),
+    )
+
+
+def _parse_relation(raw: dict[str, object]) -> Relation:
+    return Relation(
+        _parse_text(raw, "from"),
+        _parse_text(raw, "to"),
+        _parse_text(raw, "relationType"),
+        _parse_tag(raw),
+    )
+
+
+def _parse_header(raw: dict[str, object]) -> Header:
+    return Header(
+        _parse_text(raw, "repo_name"),
+        _parse_text(raw, "repo_root"),
+        _parse_tag(raw),
+    )
+
+
+def parse_record(raw: object) -> Entity | Relation | Header:
+    """Parse one decoded JSON line into an entity, relation, or header.
+
+    - Accepts legacy untagged records and plain-string observations.
+    - Raises `RecordError` for any other shape.
+    """
+    if not isinstance(raw, dict):
+        message = f"record must be a JSON object, found {raw!r}"
+        raise RecordError(message)
+    kind = raw.get("type")
+    if kind == "entity":
+        return _parse_entity(raw)
+    if kind == "relation":
+        return _parse_relation(raw)
+    if kind == "header":
+        return _parse_header(raw)
+    message = f"unknown record type {kind!r}"
+    raise RecordError(message)