{"id":49298774,"url":"https://github.com/project-minigraf/temporal_reasoning","last_synced_at":"2026-04-26T05:05:55.288Z","repository":{"id":349604414,"uuid":"1203062829","full_name":"project-minigraf/temporal_reasoning","owner":"project-minigraf","description":"Perfect memory. Exact reasoning. Complete history for AI agents.","archived":false,"fork":false,"pushed_at":"2026-04-20T11:28:48.000Z","size":280,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-20T16:50:57.464Z","etag":null,"topics":["ai-agents","bi-temporal","claude-code","context-management","datalog","graph-database","knowledge-graph","opencode","persistent-memory","prompts","skill","temporal-reasoning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/project-minigraf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-06T17:24:48.000Z","updated_at":"2026-04-20T11:27:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/project-minigraf/temporal_reasoning","commit_stats":null,"previous_names":["adityamukho/temporal_reasoning","adityamukho/vulcan","project-minigraf/temporal_reasoning"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/project-minigraf/temporal_reasoning","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-minigraf%2Ftemporal_reasoning","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-minigraf%2Ftemporal_reasoning/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-minigraf%2Ftemporal_reasoning/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-minigraf%2Ftemporal_reasoning/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/project-minigraf","download_url":"https://codeload.github.com/project-minigraf/temporal_reasoning/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-minigraf%2Ftemporal_reasoning/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32286274,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"online","status_checked_at":"2026-04-26T02:00:05.962Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","bi-temporal","claude-code","context-management","datalog","graph-database","knowledge-graph","opencode","persistent-memory","prompts","skill","temporal-reasoning"],"created_at":"2026-04-26T05:05:54.761Z","updated_at":"2026-04-26T05:05:55.275Z","avatar_url":"https://github.com/project-minigraf.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Temporal Reasoning\n\n**Perfect memory. Exact reasoning. Complete history.**\n\nTemporal Reasoning gives AI coding agents bi-temporal graph memory: query any past state, traverse live dependency graphs, and correlate architectural decisions with structural change — all with deterministic Datalog, no fuzzy retrieval.\n\n## Questions Only Temporal Reasoning Can Answer\n\nThese queries are impossible with git log, vector search, or key-value memory:\n\n```datalog\n; What did the dependency graph look like before the auth refactor?\n[:find ?caller ?callee\n :as-of 30\n :where [?caller :calls ?callee]]\n\n; When did this coupling first appear — and what decision caused it?\n[:find ?reason\n :where [:project/service-a :depends-on :project/service-b]\n        [?d :motivated-by ?c]\n        [?c :description ?reason]]\n\n; Which modules were coupled to the payment service when we made the DB decision?\n[:find ?module\n :as-of 15\n :where [?module :depends-on :service/payment]]\n```\n\nThis is the only tool where both the decision and the structural change live as datoms in the same graph and can be joined in a single query. See [Phase 4](ROADMAP.md) for code structure evolution from git history.\n\n## Why Temporal Reasoning?\n\nMost memory tools for agents are key-value stores or vector databases. They answer \"what do you know now?\" Temporal Reasoning answers a harder question: **\"what did you know then, and what changed?\"**\n\n**Time travel.** Every write is stamped with a transaction number. You can query the graph as it existed at any past transaction:\n\n```python\n# Decision made in session 1, transaction 3\ntransact('[[:project/db :name \"PostgreSQL\"]]', reason=\"Initial choice\")\n\n# Changed in session 4, transaction 11\nretract('[[:project/db :name \"PostgreSQL\"]]', reason=\"Switching to CockroachDB for geo-distribution\")\ntransact('[[:project/db :name \"CockroachDB\"]]', reason=\"Switching to CockroachDB for geo-distribution\")\n\n# Later: what did we think the database was before session 4?\nquery(\"[:find ?name :as-of 10 :where [:project/db :name ?name]]\")\n# → \"PostgreSQL\"\n\n# What do we think now?\nquery(\"[:find ?name :where [:project/db :name ?name]]\")\n# → \"CockroachDB\"\n```\n\n**Retraction with preserved history.** Changing your mind doesn't erase the record. Retracted facts stay in the bi-temporal log and remain queryable at their original transaction time. This means the agent can always reconstruct *why* a decision changed, not just *what* the current state is.\n\n**Exact Datalog queries, not fuzzy search.** Results are deterministic and reproducible — no embedding model, no similarity threshold, no hallucinated retrievals. A query either matches or it doesn't.\n\n**Graph traversal.** Entities are first-class nodes — not isolated key-value blobs. Store service-calls-service as a real graph edge (`:calls :project/auth-service`) and traverse it with Datalog joins. Fixed-depth transitive queries (2-hop, 3-hop) are expressed as multi-hop joins. Rules unify multiple edge types under a single named relation.\n\n**Local and offline.** A single binary and a file. No API key, no network dependency, no cloud service to go down.\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                   AI Coding Agent                        │\n│              (Claude Code, OpenCode, Codex)            │\n└─────────────────────┬───────────────────────────────────┘\n                      │\n                      ▼\n┌─────────────────────────────────────────────────────────┐\n│              Python Skill Layer                          │\n│         (vulcan.py - this repo)                         │\n│   - query(), transact() functions                     │\n│   - CLI mode                                           │\n│   - Backup/restore utilities                           │\n└─────────────────────┬───────────────────────────────────┘\n                      │\n                      ▼\n┌─────────────────────────────────────────────────────────┐\n│              Minigraf CLI (\u003e= 0.19.0)                   │\n│         (https://github.com/adityamukho/minigraf)       │\n│         (the storage engine)                       │\n│   - Bi-temporal Datalog database                      │\n│   - Transaction time + Valid time                      │\n└─────────────────────┬───────────────────────────────────┘\n                      │\n                      ▼\n┌─────────────────────────────────────────────────────────┐\n│              Graph File                                  │\n│     memory.graph (current working directory)                        │\n└─────────────────────────────────────────────────────────┘\n```\n\n## Install\n\n### Claude Code (plugin — recommended)\n\nAdd to your Claude Code `settings.json`:\n\n```json\n\"extraKnownMarketplaces\": {\n  \"temporal-reasoning\": {\n    \"source\": {\n      \"source\": \"git\",\n      \"url\": \"https://github.com/adityamukho/temporal_reasoning\"\n    }\n  }\n}\n```\n\nThen enable the `temporal-reasoning` plugin in Claude Code. Once enabled, run once to download the minigraf binary:\n\n```bash\npython install.py\n```\n\n`install.py` auto-detects your platform and downloads the correct pre-built binary (Linux x86_64/aarch64, macOS arm64/x86_64, Windows). Falls back to `cargo install minigraf` on unsupported platforms.\n\n### Manual install\n\n```bash\ngit clone https://github.com/adityamukho/temporal_reasoning\ncd temporal_reasoning\npython install.py\n```\n\n### OpenCode\n\n```bash\npython install.py\n```\n\nThis syncs the skill into `.opencode/skills/temporal-reasoning`.\n\n## Quick Start\n\n```python\nfrom vulcan import query, transact\n\n# Store a decision\ntransact(\"[[:decision/cache-strategy :decision/description \\\"use Redis\\\"]]\", \n         reason=\"Architecture decision for low-latency caching\")\n\n# Query decisions\nresult = query(\"[:find ?d :where [?e :decision/description ?d]]\")\n```\n\n## Storage Location\n\nDefault: `memory.graph` in the current working directory.\n\nOverride: `MINIGRAF_GRAPH_PATH=/custom/path python ...`\n\n## Files\n\n| File | Purpose |\n|------|---------|\n| `vulcan.py` | Python CLI wrapper |\n| `report_issue.py` | GitHub issue reporter |\n| `install.py` | Setup script |\n| `pyproject.toml` | Python packaging |\n| `tools/*.json` | Tool schemas |\n| `prompts/*.txt` | Behavioral prompts |\n| `tests/test_harness.py` | Validation tests |\n\n## Tools\n\n- **vulcan_query** — Query memory with Datalog\n- **vulcan_transact** — Store facts (reason required)\n- **vulcan_retract** — Retract facts (original stays in history)\n- **vulcan_report_issue** — File GitHub issues\n\n## Query Examples\n\n```python\n# Basic query\nquery(\"[:find ?x :where [?e :attr ?x]]\")\n\n# Temporal query (state at transaction N)\nquery(\"[:find ?x :as-of 5 :where [?e :attr ?x]]\")\n\n# Aggregation\nquery(\"[:find (count ?e) :where [?e :decision/description ?d]]\")\n\n# Single-hop graph traversal — what does api-gateway call?\nquery(\"[:find ?name :where [:project/api-gateway :calls ?svc] [?svc :name ?name]]\")\n\n# Two-hop join — transitive impact: what depends on key-store (directly or via one intermediate)?\nquery(\"\"\"[:find ?svc\n          :where [?mid :depends-on :project/key-store]\n                 [?svc :depends-on ?mid]]\"\"\")\n\n# Decision traceability — why did we choose asyncio?\nquery(\"[:find ?reason :where [:decision/asyncio-choice :motivated-by ?c] [?c :description ?reason]]\")\n\n# Typed entity query — list all stored components\nquery(\"[:find ?name :where [?e :entity-type :type/component] [?e :name ?name]]\")\n```\n\n## Cross-Session Evaluation\n\nThe repository includes a deterministic evaluation showing that persisted memory\nchanges behavior in a later session without restating the original context.\n\nRun:\n\n```bash\npytest tests/test_harness.py -q\n```\n\nSuccess means the harness demonstrates all of the following against the same\ngraph file:\n- A decision is stored in an earlier session.\n- A later session answers a cache-strategy question using that persisted\n  decision.\n- A later session derives an action-oriented plan from the same persisted\n  decision.\n\nThis evaluation is intentionally local and deterministic. It does not depend on\nlive model output, so it is suitable as repeatable evidence for the skill's\ncross-session usefulness claim.\n\n## Usefulness Benchmarks\n\nThe harness also reports two explicit benchmark-style metrics so usefulness\nclaims are tied to measurable output rather than broad narrative assertions.\n\n- Behavior consistency:\n  verifies that persisted memory drives both a later answer and a later\n  action-oriented plan toward the same stored decision.\n- Prompt compression proxy:\n  compares a short prompt that relies on memory recall with a longer prompt\n  that repeats the same decision context inline.\n\nRun:\n\n```bash\npython tests/test_harness.py\n```\n\nThe prompt-compression metric uses a simple whitespace word count as a stable\nlocal proxy for prompt size. It does not claim model-token exactness; it only\nshows that recalling stored context can reduce repeated prompt text in a later\nsession.\n\n## Skill Benchmarks\n\nSeven evals measure how the skill changes behavior versus a no-skill baseline. Each eval is seeded with a specific memory state and tests a distinct capability.\n\n| Eval | What it tests | With Skill | Without Skill |\n|------|--------------|-----------|---------------|\n| Decision storage | Persists architectural decisions with correct naming + reasons | 6/6 | 0/6 |\n| Populated retrieval | Queries memory and cites stored facts by name | 5/5 | 0/5 |\n| Cross-session preference | Discovers and applies a constraint never stated in the current conversation | 4/4 | 0/4 |\n| Conflict detection | Surfaces architectural conflicts before silently overriding decisions | 4/4 | 0/4 |\n| Entity reference storage | Stores relationships as traversable graph edges, not dead-end strings | 5/5 | 0/5 |\n| Transitive impact analysis | Traverses a multi-hop dependency chain to find all affected services | 5/5 | 0/5 |\n| Decision traceability | Follows a `:motivated-by` edge to surface the constraint behind a decision | 5/5 | 0/5 |\n| **Total** | | **34/34 (100%)** | **0/34 (0%)** |\n\nThe cross-session preference eval is the most discriminating for memory recall: the prompt says \"make sure it fits with how we do things\" with no hint that a relevant constraint exists. The skill queries memory, finds a stored no-mocks preference, and writes a test using real database connections.\n\nThe transitive impact eval is the most discriminating for graph traversal: given \"key-store is being replaced — what breaks?\" the skill executes a 2-hop Datalog join and returns a full impact chain; without it, the agent correctly admits it cannot name the affected services.\n\nSee [`evals/benchmark.md`](evals/benchmark.md) for full results and per-eval breakdowns.\n\n## Phases\n\n- **Phase 1** — Python skill layer ✓\n- **Phase 2** — Write policy, report_issue, install, skill benchmarks ✓\n- **Phase 3** — WASM bindings, MCP integration (future)\n- **Phase 4** — Code structure evolution from git history (future)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproject-minigraf%2Ftemporal_reasoning","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fproject-minigraf%2Ftemporal_reasoning","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproject-minigraf%2Ftemporal_reasoning/lists"}