list_facts
List recorded facts from repository memory, with optional filters by tag, source file, or date, to find relevant information before reading full content.
Instructions
List recorded facts, optionally filtered. Useful when you want only facts relevant to a specific area before reading them.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | ||
| source_file | No | ||
| since | No | ||
| limit | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/repo_memory/store.py:194-220 (handler)Core implementation of list_facts — reads facts.jsonl, filters by tag/source_file/since, applies limit, returns list of Fact objects.
def list_facts(root: Path, *, tag: str | None = None, source_file: str | None = None, since: str | None = None, limit: int | None = None) -> list[Fact]: path = _memdir(root) / FACTS_FILE if not path.exists(): return [] out: list[Fact] = [] for line in path.read_text(encoding="utf-8").splitlines(): line = line.strip() if not line: continue try: data = json.loads(line) except json.JSONDecodeError: continue f = Fact(**{k: data.get(k) for k in ("id", "ts", "claim", "evidence", "tags", "added_by")}) f.evidence = f.evidence or {} f.tags = f.tags or [] if tag and tag not in f.tags: continue if source_file and (f.evidence or {}).get("file") != source_file: continue if since and f.ts < since: continue out.append(f) if limit: out = out[-limit:] return out - src/repo_memory/mcp_server.py:57-64 (handler)MCP tool handler for list_facts — decorated with @mcp.tool(), delegates to store.list_facts and returns dict representations.
@mcp.tool() def list_facts(tag: str | None = None, source_file: str | None = None, since: str | None = None, limit: int = 20) -> list[dict]: """List recorded facts, optionally filtered. Useful when you want only facts relevant to a specific area before reading them.""" facts = store.list_facts(_REPO_ROOT, tag=tag, source_file=source_file, since=since, limit=limit) return [f.__dict__ for f in facts] - src/repo_memory/store.py:108-115 (schema)Fact dataclass — the return type used by list_facts, with id, ts, claim, evidence, tags, added_by fields.
@dataclass class Fact: id: str ts: str claim: str evidence: dict = field(default_factory=dict) tags: list[str] = field(default_factory=list) added_by: str | None = None - src/repo_memory/mcp_server.py:57-64 (registration)Registration of list_facts as an MCP tool via @mcp.tool() decorator on the handler function.
@mcp.tool() def list_facts(tag: str | None = None, source_file: str | None = None, since: str | None = None, limit: int = 20) -> list[dict]: """List recorded facts, optionally filtered. Useful when you want only facts relevant to a specific area before reading them.""" facts = store.list_facts(_REPO_ROOT, tag=tag, source_file=source_file, since=since, limit=limit) return [f.__dict__ for f in facts] - src/repo_memory/cli.py:50-56 (registration)CLI subcommand registration for list-facts with argument definitions (--tag, --source-file, --since, --limit, --json).
p_list_facts = sub.add_parser("list-facts", help="List facts, with optional filters.") _add_root_arg(p_list_facts) p_list_facts.add_argument("--tag") p_list_facts.add_argument("--source-file") p_list_facts.add_argument("--since", help="ISO timestamp (UTC).") p_list_facts.add_argument("--limit", type=int) p_list_facts.add_argument("--json", action="store_true", help="Emit JSON instead of table.")