How do I use NeuroWeave Timeline?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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

by Thatgfsj

Overview Schema Related Servers Score Discussions

Python

Local

🧠 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.

License: MIT Python 3.10+ PyPI: NWtimeline MCP Release v0.2.0 GitHub stars

Most tools remember results. NWT remembers evolution.

Traditional memory:  User → Context → Summary → Memory
Timeline memory:     User → Action  → Timeline Event → Evolution Graph

Every 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?	`nwt explain activation.py`
Why was this architecture chosen?	`nwt search "architecture decision"`
What happened three months ago?	`nwt history`
What decisions led to the current design?	`nwt story`
Show me the evolution graph	`nwt graph`
What did that commit actually do?	`nwt git-hook-status`
What changed between two events?	`nwt diff 1 5`
Merge small consecutive events	`nwt compact`

AI agents reach the same answers over MCP — see MCP integration.

Related MCP server: mcp-chest-memory

🌱 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 layer

Add --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 graph

That'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.py

`nwt 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 activation

`nwt 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 slow

🆕 New features (v0.3)

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 milestone

The story command groups events by importance.

`nwt diff` — compare two events

nwt diff 1 5
# Output:
# Diff: [1] → [5]
# Events: 5 between these points
# Added: new_feature.py
# Modified: main.py

`nwt 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)

Options:

--time-window 3600 — group events within 1 hour (default)
--min-group 3 — minimum group size to merge (default)

🧩 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/          # reserved for v0.2
    └── indices/            # derived, rebuildable
        ├── files.json
        └── tags.json

Everything 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
`create_event`	A persisted event with id and timestamp
`search_history`	Matching events across task/summary/reason/files/tags
`get_project_story`	Compressed project story (milestones, decisions, spine file)
`explain_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_story to load context.
For unfamiliar files: call explain_file rather than reading cold.
As work is done: call create_event with a reason explaining why.
When uncertain: call search_history with a hypothesis from the current code.

📦 安装

# from a clone (editable)
git clone https://github.com/Thatgfsj/neuroweave-timeline
cd neuroweave-timeline
pip install -e .

# from PyPI (coming soon)
pip install NWtimeline

需要 Python 3.10+。CLI 依赖于 click；MCP 服务器依赖于 mcp。两者都是自动安装的。

安装开发依赖（pytest）并运行测试套件：

pip install -e ".[dev]"
pytest -q

🗺️ Roadmap

v0.2 (this release) is the "auto-grow" cut: git hook integration, strict mode, file biography, and event templates. The timeline fills itself now.

v0.3 — agent integration. Drive NWT through Claude Code, Cursor, and OpenAI Agents to find the gaps.
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 tools

create_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).

ParametersJSON Schema

Name	Required	Description	Default
`tags`	No
`task`	Yes
`files`	No
`parent`	No
`reason`	No
`summary`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It states it appends an event and returns the persisted dict, but does not discuss side effects, idempotency, authorization needs, or what happens with the 'parent' parameter (e.g., replacing branch). Limited transparency for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description uses a docstring format with clear sections (Args, Returns). It is front-loaded with the main purpose and every sentence contributes meaningful information. While not extremely short, it is appropriately sized for the number of parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers all parameters (two required) and explains the return value. However, it does not mention error conditions, file path conventions, or tag formatting rules. Given the complexity (6 params, no annotations), additional context would be beneficial but not strictly necessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description adds crucial meaning to each parameter: task is imperative title, summary describes what was done, reason is strongly encouraged for history, files are project-relative paths, tags are free-form labels, and parent indicates linear chain via id or null for new branch. This compensates effectively for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with 'Append a new event to the project's timeline,' clearly stating the verb and resource. It distinguishes this tool from siblings (which are read/search operations) by focusing on creation of timeline events.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage is for adding events to a timeline, but does not explicitly state when to use this instead of siblings or any exclusions. Context is clear but lacks definitive guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 ..." }

ParametersJSON Schema

Name	Required	Description	Default
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries burden. It shows output format via Returns and Example, implying it's a query tool. But it doesn't explicitly state it's read-only or disclose side effects/permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is concise: first sentence states purpose, then Args, Returns, Example. Every part is useful with no redundancy. Well-structured for easy scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with output schema, the description covers purpose, parameter, and return format. Lacks error handling (e.g., what if file doesn't exist) and edge cases, but overall sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description adds full meaning: 'Project-relative path to the file (e.g. ``activation.py``)'. This clarifies format and gives an example, going beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Explain why a file exists', providing a specific verb and resource. The sibling tools (create_event, get_project_story, search_history) are distinct, so no confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. No mention of when not to use or prerequisites. The agent must infer usage from the name and example alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`max_milestones`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It explains selection criteria (up to max_milestones, all decision events) and mentions the compressed nature. However, it does not disclose error conditions, performance implications, or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with bullet points and a returns section. Every sentence adds value; no fluff. It is appropriately front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has one parameter and an output schema (not shown but indicated). The description covers the return structure comprehensively, including a human-readable text field. It is mostly complete but could include when to use it or what the 'compressed' means in practice.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explicitly explains the sole parameter 'max_milestones' by stating it limits the number of milestone events in the story. This adds value beyond the schema, which only provides a default. Schema coverage is 0%, so the description fully compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a 'compressed project story' and lists its contents (name, timestamps, milestones, spine file, decision events, human-readable text). It distinguishes from siblings like 'create_event' and 'explain_file' by focusing on retrieval of a summary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide guidance on when to use this tool versus alternatives (e.g., search_history), nor does it mention prerequisites or exclusions. The context signals show no usage hints.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes
`search_tags`	No
`search_files`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses case-insensitive substring matching, searched fields, ordering by id ascending, and return structure. Does not mention performance or error conditions, but provides solid behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise, front-loaded with 'Search the timeline.' Structured Args and Returns sections with no wasted sentences. All information earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and low schema coverage, description covers search scope, parameters, and return format. Output schema exists, so return details are optional. Lacks details on pagination or performance, but adequate for typical search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It explains each parameter: query as case-insensitive substring, limit as cap, search_files/search_tags as boolean inclusions, and defaults. Adds meaning beyond schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search the timeline' with specific verb and resource, listing matched fields (task, summary, etc.), and distinguishes from siblings that create events, explain files, or get project story.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives; however, siblings have distinct actions, so usage is implied. No exclusions or when-not advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0

Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

Four tools cover the core functionalities of a timeline system (creation, explanation, overview, search) without excess or deficiency.

Completeness4/5

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

ActivityStale

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

innernet
live.innernet
Your versioned memory across every AI tool — context maps, personal memory, and tasks over MCP.
Knowledge & Memory Project Management
2
memnode
dev.memnode
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Knowledge & Memory Autonomous Agents Agent Orchestration
2
MemoryRouter A
ai.memoryrouter
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Knowledge & Memory Search
101
mifactory-agent-memory C
io.github.mifactory-bot
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Knowledge & Memory Autonomous Agents Agent Orchestration
22

Related MCP Servers

tentra
Knowledge & Memory Code Analysis Software Architecture
rdanieli
A
license
B
quality
F
maintenance
Memory for AI coding agents. Persistent code graph + AI architecture diagrams. 32 MCP tools
Updated 3 months ago (2026-06-11 18:48 UTC)
32
69
5
MIT
mcp-chest-memory
Knowledge & Memory Developer Tools
siosig
A
license
Not graded
quality
B
maintenance
Provides a persistent, local-first memory for coding agents over MCP, enabling automatic recall and recording of past work, failures, and decisions to reduce repetition and token usage.
Updated 2 months ago (2026-06-30 00:07 UTC)
MIT
cortexmem
Knowledge & Memory Version Control Developer Tools
Ashprakash
A
license
Not graded
quality
D
maintenance
Persistent memory for AI coding agents. Builds semantic memory from git history and codebase, searchable via MCP tools.
Updated 6 months ago (2026-03-16 04:48 UTC)
12
2
MIT
ContextWeave
Knowledge & Memory Developer Tools
deyavinaba597-pixel
A
license
Not graded
quality
C
maintenance
Universal project memory engine that extracts knowledge from code and git history, enabling AI assistants to query full project context via MCP.
Updated 2 months ago (2026-06-24 15:45 UTC)
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Thatgfsj/neuroweave-timeline'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

🧠 NeuroWeave Timeline (NWT)

💬 What you can ask

🌱 Auto-grow: timeline from git commit

🚀 30-second quick start

👀 A tour of the output

nwt history — what happened, in order

nwt graph — the evolution as a tree

nwt story — 100 events compressed to one page

nwt explain activation.py — why a file exists

🆕 New features (v0.3)

Event importance

nwt diff — compare two events

nwt compact — merge small events

🧩 How it works

🔌 MCP integration

📦 安装

🗺️ Roadmap

🤝 Contributing

🔒 Security

📄 License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

🌱 Auto-grow: timeline from `git commit`

`nwt history` — what happened, in order

`nwt graph` — the evolution as a tree

`nwt story` — 100 events compressed to one page

`nwt explain activation.py` — why a file exists

`nwt diff` — compare two events

`nwt compact` — merge small events