NeuroWeave Timeline
This server provides MCP tools to record and explore a project's evolution timeline as structured events.
create_event: Append a new event to the timeline with task, summary, reason, files, tags, and optional parent.
search_history: Search the timeline for events by substring, with optional file and tag matching and a result limit.
get_project_story: Get a compressed project summary including milestones, spine file, decision events, and a human-readable text rendering.
explain_file: Ask why a file exists, returning its creating event, modifying events, and the stated reason.
Automatically logs timeline events from git commits via a post-commit hook, allowing the project history to grow with each commit and providing git hook status checks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@NeuroWeave Timeline Explain the history of activation.py"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
NeuroWeave Timeline (NWT)
Process memory for AI agents and humans. NWT remembers how a project became what it is — not just what it is now.
Most tools remember results. NWT remembers evolution.
Traditional memory: User → Context → Summary → Memory
Timeline memory: User → Action → Timeline Event → Evolution GraphEvery meaningful action in your project — a decision, a refactor, a file creation, a bug fix — becomes a node in a durable timeline. The links between nodes form an Evolution Graph that explains why the project looks the way it does today.
What you can ask
Question | One-liner |
Why does this file exist? |
|
Why was this architecture chosen? |
|
What happened three months ago? |
|
What decisions led to the current design? |
|
Show me the evolution graph |
|
What did that commit actually do? |
|
What changed between two events? |
|
Merge small consecutive events |
|
AI agents reach the same answers over MCP — see MCP integration.
Related MCP server: ContextWeave
Auto-grow: timeline from git commit
The single biggest reason NWT timelines are empty is friction. The v0.2 fix is a post-commit hook that logs an event on every commit — no human or agent typing required.
nwt init
nwt install-git-hook
git commit -m "Refactor retrieval layer" -m "Reason: lookup latency was high"
nwt: logged [12] Refactor retrieval layerAdd --strict to refuse events without a Reason: line, and
--ai-command "claude -p" to let an external model fill the reason
when the human didn't. See docs/git-hook.md.
30-second quick start
pip install -e .
cd your-project
nwt init
nwt log "Add activation engine" \
--files activation.py \
--reason "retrieval was slow"
nwt history
nwt graphThat's it. Storage is plain JSON under .nwt/. No database, no
embeddings, no vendor lock-in, no daemon.
A tour of the output
nwt history — what happened, in order
[1] 2026-06-15 Project scaffolded [setup, milestone]
reason: Kickoff the MVP
files: pyproject.toml, README.md
[2] 2026-06-15 Add memory engine [core, milestone]
reason: Need a place to put things
files: memory.py
[3] 2026-06-15 Add activation spreading [memory, optimization]
reason: Retrieval was sequential and slow
files: activation.py, retriever.py
[4] 2026-06-15 Add decay mechanism [memory]
reason: Stale nodes should fade
files: activation.py
[5] 2026-06-15 Vectorize activation [refactor, performance]
reason: Loop was the hot path in profiling
files: activation.pynwt graph — the evolution as a tree
○ 1 Project scaffolded
│
│ 2 Add memory engine
├─ sibling → [ 4] Add decay mechanism
└─ extends → [ 3] Add activation spreading
│
│ 3 Add activation spreading
│
│ 5 Vectorize activationnwt story — 100 events compressed to one page
# memory-engine-demo — evolution summary
span: 2026-06-15 → 2026-06-15 (5 events)
milestones:
- 1 Project scaffolded — Kickoff the MVP
- 2 Add memory engine — Need a place to put things
- 3 Add activation spreading — Retrieval was sequential and slow
- 4 Add decay mechanism — Stale nodes should fade
- 5 Vectorize activation — Loop was the hot path in profiling
spine file: activation.py
decisions (events with stated reasons):
- [1] Project scaffolded: Kickoff the MVP
- [2] Add memory engine: Need a place to put things
...nwt explain activation.py — why a file exists
# activation.py
created in: event 3
modified in: 4, 5
reason:
Retrieval was sequential and slowNew in v0.2
Events chain automatically
nwt log appends after the latest event by default, so a plain
sequence of logs forms one linear history. Start an explicit branch
with --parent none, or continue after a specific event with
--parent ID.
Event importance
Events now have an importance field: low, normal (default), high, milestone.
nwt log "Fix login bug" --summary "..." --importance high
nwt log "Project launched" --summary "..." --importance milestoneThe story command reports events grouped by importance.
nwt diff — compare two events
nwt diff 1 5
# Output:
# Diff: [1] → [5]
# Events: 5 between these points
# Added: new_feature.py
# Removed: old_feature.py
# In both (likely modified): main.pynwt compact — merge small events
When you have many small consecutive events with the same tags, compact them:
nwt compact
# Compacted: 50 → 35 events (merged 15)
# backup: .nwt/snapshots/pre-compact-20260920T120000Options:
--time-window 3600— group events within 1 hour (default)--min-group 3— minimum group size to merge (default)--dry-run— preview the merge without touching disk
Compact backs up timeline/, relations/ and the counter to
.nwt/snapshots/ before rewriting, and remaps parents, typed
relations, indices, and the id counter onto the renumbered events.
How it works
NWT lives in your project as a single .nwt/ directory:
your-project/
└── .nwt/
├── metadata.json # project name, schema version
├── .counter.json # next event id
├── timeline/ # one JSON file per event
│ ├── 000001.json
│ ├── 000002.json
│ └── ...
├── relations/ # typed edges out of each source event
├── snapshots/ # pre-compact backups land here
└── indices/ # derived, rebuildable
├── files.json
└── tags.jsonEverything is JSON, atomically written. The whole workspace is
grep-friendly and git diff-friendly. See
docs/architecture.md for the rationale.
MCP integration
For agent developers — NWT ships an MCP server exposing the same answers as tools:
Tool | Returns |
A persisted event with id and timestamp | |
Matching events across task/summary/reason/files/tags | |
Compressed project story (milestones, decisions, spine file) | |
Created/modified-in + earliest reason for a file |
Wire it up in your MCP client:
{
"mcpServers": {
"nwt": {
"command": "nwt-mcp",
"env": { "NWT_ROOT": "/absolute/path/to/your/project" }
}
}
}The server picks the workspace from $NWT_ROOT if set, else its own
cwd. See docs/mcp.md for the recommended agent loop:
Session start: call
get_project_storyto load context.For unfamiliar files: call
explain_filerather than reading cold.As work is done: call
create_eventwith areasonexplaining why.When uncertain: call
search_historywith a hypothesis from the current code.
安装
# from PyPI
pip install NWtimeline
# from a clone (editable)
git clone https://github.com/Thatgfsj/neuroweave-timeline
cd neuroweave-timeline
pip install -e .需要 Python 3.10+。CLI 依赖于 click;MCP 服务器依赖于 mcp。两者都是自动安装的。
安装开发依赖(pytest)并运行测试套件:
pip install -e ".[dev]"
pytest -qRoadmap
v0.2 (this release) is the "auto-grow" cut: git hook integration with
strict mode and AI-filled reasons, automatic event chaining, the
importance field, diff, and compact. The timeline fills itself now.
v0.3 — snapshots (
nwt snapshot/nwt restore) and deeper git linkage (commit SHAs on every event,nwt rewind).v0.4 — multi-agent collaboration history (concurrency-safe writes, per-author identity).
v0.5 — NWC integration, only if NWT earns it on its own.
See docs/roadmap.md and
docs/standalone.md for the full story.
Contributing
Issues and PRs are welcome. The whole project is ~1,500 lines of
Python plus docs — easy to read end-to-end. Start with
docs/architecture.md for the layout and
CONTRIBUTING.md for the workflow.
Security
NWT stores only what you give it, on disk, in your project's .nwt/.
It does not phone home, does not read environment variables other
than NWT_ROOT, and writes nowhere else. The .gitignore refuses
to track tokens, keys, or .env files. See
SECURITY.md for the full policy.
License
MIT — see LICENSE.
Available Tools
4 toolscreate_eventA
Append a new event to the project's timeline.
Args:
task: Short imperative title (e.g. "Add activation engine").
summary: One or two sentences describing what was done.
reason: Why this change was made. Strongly encouraged — this is
what turns NWT from a log into a history.
files: Project-relative file paths this event touched.
tags: Free-form labels (e.g. ["memory", "optimization"]).
parent: Id of the preceding event in the linear chain, or null
to start a new branch.
Returns: The persisted event as a dict (including its allocated id and timestamp).
Inputs: task (required), summary (required), tags, files, +2 more. Returns: object
explain_fileA
Explain why a file exists.
Args:
file_path: Project-relative path to the file (e.g. activation.py).
Returns:
A dict with keys file, created_in, modified_in,
events, reason and a human-readable text rendering.
Example: >>> explain_file("activation.py") { "file": "activation.py", "created_in": 23, "modified_in": [45, 67], "reason": "Improve graph retrieval performance.", "text": "activation.py\n created in event 23\n ..." }
Inputs: file_path (required). Returns: object
get_project_storyA
Return a compressed project story.
The story contains:
* project name and first/last event timestamps
* up to max_milestones milestone events
* the file that changed most often (the "spine file")
* all decision events (those with a non-empty reason)
Returns:
A dict mirroring the structure of :class:ProjectStory, plus a
human-readable text rendering for direct LLM consumption.
Inputs: max_milestones. Returns: object
search_historyA
Search the timeline.
Args: query: Substring to search for (case-insensitive). Matched against task, summary, reason, file paths, and tags. limit: Cap on the number of results. search_files: Include file paths in the search. search_tags: Include tags in the search.
Returns:
A list of matching events, ordered by id ascending. Each event
is a dict; see create_event for the field set.
Inputs: query (required), limit, search_tags, search_files. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clear, distinct purpose: creating events, explaining a file, retrieving a project story, and searching history. There is no overlap or ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case (create_event, explain_file, get_project_story, search_history), making it easy to predict function.
Four tools cover the core functionalities of a timeline system (creation, explanation, overview, search) without excess or deficiency.
The set covers creation and querying well, but lacks direct event retrieval by ID and update/delete operations. However, these may be intentionally omitted for an immutable timeline.
Maintenance
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Shared memory for your AI tools: tasks, notes and context every tool can read and write over MCP.
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Related MCP Servers
- AlicenseAqualityDmaintenancePersistent memory for AI coding agents. Builds semantic memory from git history and codebase, searchable via MCP tools.44 npm2MIT
- AlicenseNot gradedqualityDmaintenanceUniversal project memory engine that extracts knowledge from code and git history, enabling AI assistants to query full project context via MCP.MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI coding agents and IDEs to capture conversations, extract structured knowledge into a queryable graph database, and recall past decisions, patterns, files, and errors across all projects and workspaces. Provides persistent memory tools for saving, searching, and cleaning up knowledge via MCP.2-
- AlicenseNot gradedqualityBmaintenanceProvides persistent memory for AI coding agents, enabling them to save, search (hybrid vector/BM25/concept graph), list sessions, and forget memories via MCP tools.11 npmApache 2.0