Metadata-Version: 2.4
Name: NWtimeline
Version: 0.1.0
Summary: Process memory for AI agents and humans. Records how a project became what it is.
Author: NeuroWeave
License: MIT
Project-URL: Homepage, https://github.com/Thatgfsj/neuroweave-timeline
Project-URL: Repository, https://github.com/Thatgfsj/neuroweave-timeline
Project-URL: Issues, https://github.com/Thatgfsj/neuroweave-timeline/issues
Project-URL: Changelog, https://github.com/Thatgfsj/neuroweave-timeline/blob/main/CHANGELOG.md
Keywords: timeline,memory,agent,mcp,process-history
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Version Control
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: mcp>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Dynamic: license-file

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

[![CI](https://img.shields.io/github/actions/workflow/status/Thatgfsj/neuroweave-timeline/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=CI)](https://github.com/Thatgfsj/neuroweave-timeline/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/)
[![PyPI: NWtimeline](https://img.shields.io/pypi/v/NWtimeline?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/NWtimeline/)
[![MCP](https://img.shields.io/badge/MCP-std.io-orange.svg?style=flat-square)](https://modelcontextprotocol.io)
[![Release v0.2.0](https://img.shields.io/badge/release-v0.2.0-blue.svg?style=flat-square)](https://github.com/Thatgfsj/neuroweave-timeline/releases/tag/v0.2.0)
[![GitHub stars](https://img.shields.io/github/stars/Thatgfsj/neuroweave-timeline?style=flat-square)](https://github.com/Thatgfsj/neuroweave-timeline/stargazers)

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

AI agents reach the same answers over MCP — see [MCP integration](#-mcp-integration).

## 🌱 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.

```bash
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`](docs/git-hook.md).

---

## 🚀 30-second quick start

```bash
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
```

---

## 🧩 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`](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`](docs/mcp.md#create_event) | A persisted event with id and timestamp |
| [`search_history`](docs/mcp.md#search_history) | Matching events across task/summary/reason/files/tags |
| [`get_project_story`](docs/mcp.md#get_project_story) | Compressed project story (milestones, decisions, spine file) |
| [`explain_file`](docs/mcp.md#explain_file) | Created/modified-in + earliest reason for a file |

Wire it up in your MCP client:

```json
{
  "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`](docs/mcp.md) for the recommended agent loop:

1. **Session start:** call `get_project_story` to load context.
2. **For unfamiliar files:** call `explain_file` rather than reading cold.
3. **As work is done:** call `create_event` with a `reason` explaining *why*.
4. **When uncertain:** call `search_history` with a hypothesis from the current code.

---

## 📦 安装

```bash
# 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）并运行测试套件：

```bash
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`](docs/roadmap.md) and
[`docs/standalone.md`](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`](docs/architecture.md) for the layout and
[`CONTRIBUTING.md`](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`](SECURITY.md) for the full policy.

---

## 📄 License

MIT — see [LICENSE](LICENSE).
