# Obsidian-Inspired CTM Resource Map

Date: 2026-05-16

## Why this exists

Obsidian is useful because notes are not isolated documents. The product keeps
links, backlinks, local graph, saved views, workspaces, and commands close to the
object the user is already looking at. CTM has the same need, but the objects are
sessions, provider-native agent sessions, JSONL transcripts, prompts, harvested
messages, projects, models, skills, and memories.

The CTM implementation must not become a Markdown vault or a second knowledge
store. Resource Map is a read projection over existing CTM data:

- `ctm_sessions` owns the CTM tab/session identity.
- `agent_sessions` owns provider-native session identity and JSONL provenance.
- `prompt_usage` owns explicit prompt-to-session usage.
- `prompt_executions` owns harvested user/assistant message snippets.
- `session_analyses` owns derived topics and skill signals.

## Obsidian Prior Art

Official Obsidian docs show the product shape CTM should copy, not the storage
model:

- Core plugins include Backlinks, Outgoing links, Bases, Canvas, Graph view,
  Workspaces, Command palette, Quick switcher, Search, Tags, and Slash commands:
  https://obsidian.md/help/plugins
- Bases views let a user configure filtered/sorted views over files and
  properties, instead of creating one-off lists:
  https://obsidian.md/help/bases/views
- Graph view shows note nodes and links; Local Graph scopes the graph to the
  active note and adjustable depth:
  https://obsidian.md/help/plugins/graph
- Canvas is a visual planning layer over linked notes, attachments, and web
  pages, stored separately as JSON Canvas:
  https://obsidian.md/help/plugins/canvas
- Workspaces save task-specific layouts:
  https://obsidian.md/help/plugins/workspaces
- Command palette exposes actions with fuzzy matching and pinned commands:
  https://obsidian.md/help/plugins/command-palette

## CTM Translation

Resource Map is the first safe slice:

| Obsidian idea | CTM equivalent | Current implementation |
| --- | --- | --- |
| Backlinks | "Where is this prompt/session referenced?" | Prompt usage and session prompt links |
| Outgoing links | "What does this object point to?" | Agent IDs, prompts, messages, project, model, topics, skills |
| Local graph | "What is near the current object?" | Nodes and edges for one session or prompt |
| Bases views | Saved operational views | API emits built-in views: recent sessions, prompt reuse, session fidelity |
| Canvas | Visual planning board | Deferred until resource edges are stable |
| Workspaces | Task-specific layout snapshots | Deferred; use existing tabs/workspaces first |
| Command palette | Discoverable action registry | Deferred; Resource Map action becomes palette-ready later |

## Data Contract

Endpoint:

```http
GET /api/resource-links?type=session&id=<ctm-or-agent-session-id>&limit=36
GET /api/resource-links?type=prompt&id=<prompt-id>&limit=36
GET /api/resource-views?limit=20
```

Response shape:

```json
{
  "resource": {
    "type": "session",
    "id": "ctm-session-id",
    "requestedId": "input-id",
    "label": "Human title",
    "meta": {}
  },
  "backlinks": [],
  "outgoing": [],
  "graph": {
    "nodes": [],
    "edges": []
  },
  "stats": {
    "backlinks": 0,
    "outgoing": 0,
    "nodes": 0,
    "edges": 0
  }
}
```

Each edge carries evidence such as table name, row id, field name, session id, or
timestamp. This is intentional: session bugs often come from identity ambiguity,
so the UI must be able to explain why a link exists.

## UI

Session Review has a `Context Map` action next to `Linked Prompts`.

Prompt Editor has a compact `Map` button in the prompt meta bar.

The modal renders three panes:

- `Backlinks`: resources that point at this resource.
- `Outgoing`: resources this resource points to.
- `Local Graph`: compact node cloud plus edge list.

The modal is intentionally not a force-directed graph yet. A table/list-first
local graph is easier to inspect, test, and use on phone/remote access. Canvas or
2D graph can sit on top of the same API later.

## Non-Goals

- Do not duplicate transcript content into a new table.
- Do not create another CTM-to-agent-session mapping table.
- Do not scan full JSONL files synchronously from the Resource Map request path.
- Do not infer private memory links unless Wall-E explicitly publishes a stable
  edge source.

## Correctness Checks

- Session lookups accept either CTM session id or provider-native agent session
  id and resolve through `getSessionIdentity`.
- CTM session to agent session remains 1:N.
- Prompt usage rows can point at CTM ids or agent ids; Resource Map resolves both
  back to a CTM session when rendering prompt backlinks.
- All SQL uses parameter binding. The only dynamic SQL fragments are placeholder
  counts and known table/column names.
- UI HTML escapes resource labels and metadata before inserting modal markup.

## Future Phases

1. Add a command-palette command: `Open Context Map`.
2. Add user-defined saved views over the resource graph, similar to Bases.
3. Add a Canvas-style board only after resource edges have enough fidelity.
4. Add Wall-E memory entities as optional edge providers with explicit
   provenance, not implicit context injection.
5. Add graph-depth controls and filters for node types, provider, project, and
   stale/fresh edge status.
